Files
java-word-pdf/docs/agent/chart.md
T
Pjandro f3ff218686
PR checks / web (pull_request) Successful in 9s
PR checks / java (pull_request) Successful in 5m26s
Main: tests, deploy, autotests / web (push) Successful in 9s
Main: tests, deploy, autotests / images-web (push) Successful in 23s
Main: tests, deploy, autotests / java (push) Successful in 1m30s
Main: tests, deploy, autotests / images-app (push) Successful in 49s
Main: tests, deploy, autotests / deploy (push) Successful in 2m13s
Main: tests, deploy, autotests / autotests (push) Successful in 17s
Main: tests, deploy, autotests / rollback (push) Has been skipped
feat(core): собственный рендер OMML→PNG и полный FOP-конфиг шрифтов
Замена JEuclid/AWT-ветки формул на детерминированный растер только
бандл-шрифтами jar (без fontconfig); FOP-конфиг дополняется всеми
бандл-начертаниями при каждом declare — иначе общая FopFactory
замораживает fopconf первого документа и теряет глифы.

MathModel/MathRenderer: OMML (§22.1) → дерево боксов → PNG 300 dpi
(только GlyphFont/fontbox, без java.awt.Font); метрики боксов равны
габариту paint (пределы nary/sPre не обрезаются канвой). Unsupported
конструкция или переполнение бюджета — текстовая деградация (m:t).
Inline-картинка опускается раном w:rPr/w:position на базовую линию
строки (FOP ставит инлайн-графику нижним краем на базу; AUDIT-FIX
baseline-shift). Байтовое правило 6 MathFallbackNormalizer (перед
GlyphCoverage) срезает unsupported-формулы до загрузки docx4j; формула
в wps:txbx уходит в docx4j-фолбэк mathText.

JEuclid исключён из pom (de.rototor jeuclid-core/jeuclid-fop); порядок
zip-правил сдвинут (MathFallback → 6). Порядок сканов шрифтов закрыт
гейтом FontsBundledOnlyInvariantTest + BundledFontAliases (единый
алиас-реестр вместо рефлексивных мутаций реестра).

Счётчики: 63 класса / 1004 теста (core 57/956, app 6/48); JaCoCo
BRANCH core 0.8518. Доки: pipeline/render-limitations/repo-map/
testing/doc-bridge/MEM_USAGE_UPGRADE синхронизированы.
2026-11-20 23:51:40 +03:00

8.4 KiB
Raw Blame History

читать при правке internal/chart. Авторитетно наравне с AGENTS.md.

Нормативный источник любых правок — ECMA-376 (docs/standards/ooxml/: графики §21.2, diagram-разметка §21.4, пресет-геометрия Annex D + полные наборы XSD schema/strict//schema/transitional/; поведение Word — ms-oi29500.md, ms-odrawxml.md), а не догадки по исходникам LibreOffice/Word. Формулировки из стандарта при ссылке — с номером секции (§21.2.2.132 и т.п.). Эмпирические калибровки (камера, PIE_DEPTH) менять только вместе с пиксельными тестами. Фикстуры могут быть невалидны — код под фикстуру не правится, правится фикстура (после проверки по XSD/секции).

Java2D → PNG 300 dpi (ChartRenderer.DPI = 300, PADDING = 4.0, растр × DPI/72, размеры в пунктах, EMU→pt cx/12700.0). Потолок растра ChartRenderer.MAX_PIXELS = 16_777_216 (4096², 64 МБ ARGB): при превышении fitDpi uniform-но понижает эффективный dpi (геометрия в пунктах и безразмерные пропорции не меняются; 24″-график: 208 МБ → 64 МБ, dpi 300 → ≈171); SmartArtRenderer использует тот же DPI/fitDpi. ChartSpec.parse (enum Type: PIE, PIE3D, DOUGHNUT, BAR, BAR_HORIZONTAL, LINE, AREA, SURFACE3D, AREA3D, BAR3D, LINE3D, RADAR, SCATTER, BUBBLE, STOCK, OF_PIE, SURFACE, UNSUPPORTED). c:autoTitleDeleted (§21.2.2.7, val опущен — default true) применяется только при отсутствии c:title (MS-OI29500 §2.1.1431(a)) — явный заголовок показывается при любом флаге; при отсутствии c:title и val=0 рисуется автозаголовок. Пустой/пробельный c:title (или val=0 без c:title) — автозаголовок Office (MS-OI29500 §2.1.1561(a)): одиночный ряд с именем → имя ряда (любой тип графика), иначе ChartSpec.AUTO_TITLE = "Название диаграммы"; несколько абзацев a:p склеиваются '\n' (жёсткий перенос в DrawMlText). Регрессии — ChartSpecTest#emptyTitleSingleSeriesBar_usesSeriesName, #deletedTitleWithText_stillShown, #deletedTitleValOmitted_stillShown, #multiSeriesDoughnut_placeholderNotSeriesName, #multiParagraphTitle_joinedWithNewlines. Палитра accent1..6 темы; легенда по умолчанию снизу; overlay (§21.2.2.132) рисуется поверх области построения, место не резервирует.

Пейнтеры: CartesianPainter (2-D line/bar/area; c:grouping stacked/percentStacked §21.2.2.76 — ряд рисуется накопленной суммой через ChartRenderer.stackedCumulative), PiePainter (PIE_DEPTH = 0.22, PIE_FIT = 0.865), Surface3dPainter (камера — регрессия cameraMatchesWordReference: DEPTH_RATIO = 0.705, HEIGHT_RATIO = 0.664, GUTTER_LEFT/RIGHT = 0.1485, GUTTER_TOP = 0.116, GUTTER_BOTTOM = 0.146, свет LIGHT_X/Y/Z = 0.83/0.48/0.28; c:rAngAx=true приоритетнее c:perspective (MS-OI29500 §2.1.1516(b)); c:wireframe §21.2.2.205 — только каркас), ScatterPainter (радиус пузыря sqrt при c:sizeRepresents="area" §21.2.2.128), RadarPainter (спицы от 12 часов), StockPainter (upDownBars обводятся контуром, дефолт чёрный 0.75pt), OfPiePainter (MS-OI29500 §2.1.1507(a), §2.1.1545(a)), Surface2dPainter (контурная карта §21.2.2.204, marching squares, изолинии по c:bandFmts §21.2.2.13/.14), Cartesian3dPainter (bar3D/line3D/area3D §21.2.2.19/.101/.122, c:shape §21.2.3.44), SmartArtRenderer (кэш word/diagrams/drawing1.xml через relationship …/office/2007/relationships/diagramDrawing; формы — PresetGeometry из a:prstGeom, семь пресетов дословно из presetShapeDefinitions.xml; оператор ?: = «if x > 0 then y else z» (ISO/IEC 29500-1, не x != 0); углы в Arc2D — со знаком минус; текст — DrawMlText, шрифты через BundledFontAliases.bundledFamily; autofit только normAutofit §21.1.2.1.2/.3; dgm:prSet/@phldrT не рисуется).

Защитные лимиты против враждебного chart-XML: ChartSpec.MAX_POINTS = 100_000 (c:pt/@idx §21.2.2.150/.151, c:ptCount §21.2.2.152 — ST_UnsignedInt без верхней границы; отказ IllegalArgumentException до предвыделения списка), ChartRenderer.MAX_TICKS = 1000 (шаг ≤ 0/NaN/слишком мелкий в axisBounds заменяется niceUnit 1/2/5·10ⁿ), DrawingPreRenderer.MAX_EXTENT_EMU = 22_000_000 (≈24″; при cx/cy вне капа объект оставляется как есть + warn, картинка не рендерится — регрессия hugeExtentChart_removedNotOom). Бросок перехватывает catch в DrawingPreRenderer.renderChart → штатная деградация «объект удалён + warn». Обход pkg.getParts() — только по снимку списка (вставка media-частей addChartMedia→addPart→loadPart мутирует реестр → CME); rels частей — part.getRelationshipsPart(), не getOwningRelationshipPart(); обход XML обязан раскрывать JAXBElement.

Combo (Word «Комбинированная», §21.2.2.145): несколько групп в одном c:plotArea (c:barChart + c:lineChart/c:areaChart), каждая со своими c:axId (§21.2.2.9). parse привязывает группы по id осей: Series.renderAs (семейство отрисовки), Series.grouping, Series.valAxis + ChartSpec.secondaryValAxis (обычно c:axPos="r"); spec.valAxis/catAxis — first-wins. CartesianPainter рисует семейства в порядке BAR→AREA→LINE, каждая серия масштабируется по своей оси, вторичная ось — линия справа + подписи справа.

chart-PNG media-части вставляются вручную (DrawingPreRenderer.addChartMedia: newPartForContentType → setBinaryData → rels.addPart), БЕЗ BinaryPartAbstractImage.createImagePart: тот пишет PNG во временный файл и декодирует его обратно (ImageInfo) ради mime и размеров, которые нам и так известны — mime заведомо image/png, размер задаёт wp:extent; PNG-decode в exported-пути — верхняя строка потребления памяти (JFR-замер 25 фикстур). Имена /word/media/chart-N.png (DrawingPreRenderer.CHART_MEDIA_URI_PREFIX): уникальность — счётчик с проверкой реестра пакета (PartName.generateUniqueName уникальность НЕ даёт — конкатенация), RENAME_IF_NAME_EXISTS — при коллизии с media враждебного документа наша часть переименовывается, а не затирает чужую. ChartImageHandler (вешается foSettings.setImageHandler в WordPdfConverter) возвращает null из compressedVariant для chart-* — docx4j «Compress Pictures» (CR-029) для них не ресемплит растры и даже не декодирует их при экспорте (PictureCompression.compress декодирует ВСЕГДА); режим word (порог 300 ppi) наши 300-dpi растры и не трогал по размеру, экономия — именно пропуск decode/resample. Медиа документов (фото/скрины) остаются в штатном docx4j-режиме CR-029. Регрессии: chartMedia_notDownsampled, DrawingPreRendererTest, ChartImageHandlerTest.