Files
java-word-pdf/docs/agent/chart.md
T
Pjandro de9995bba3
PR checks / web (pull_request) Successful in 43s
PR checks / java (pull_request) Successful in 1m51s
Main: tests, deploy, autotests / web (push) Successful in 58s
Main: tests, deploy, autotests / images-web (push) Successful in 31s
Main: tests, deploy, autotests / java (push) Successful in 1m38s
Main: tests, deploy, autotests / images-app (push) Successful in 49s
Main: tests, deploy, autotests / deploy (push) Failing after 2m46s
Main: tests, deploy, autotests / autotests (push) Has been skipped
Main: tests, deploy, autotests / rollback (push) Successful in 2m20s
core: chart-PNG без docx4j-декода и без пересжатия CR-029 (−23% alloc chart-документов)
DrawingPreRenderer.swapForPicture вставляет media-часть вручную
(newPartForContentType → setBinaryData → rels.addPart, имена
/word/media/chart-*): createImagePart писал temp-файл и декодировал
PNG обратно ради mime/размеров, которые нам и так известны.
ChartImageHandler (foSettings.setImageHandler) возвращает null из
compressedVariant для chart-* — «Compress Pictures» не ресемплит и не
декодирует наши 300-dpi растры; медиа документов остаются в штатном
docx4j-режиме. Замер (25 фикстур × 6 прогонов): chart-types.docx
657→507 МБ alloc (тёплый), суммарно 11640→10604 МБ, прочие 23 файла
±0%; ретеншн не изменился (144 MiB после GC), temp-файлов 0.
Регрессии: chartMedia_notDownsampled, DrawingPreRendererTest,
ChartImageHandlerTest.
2026-11-02 21:36:10 +00:00

8.5 KiB
Raw Blame History

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

Нормативный источник любых правок — ECMA-376 (docs/standards/docx/: графики §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, шрифты через BundledFontMapper.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.