Files
java-word-pdf/docs/agent/chart.md
T
Pjandro f41ac54072
PR checks / web (pull_request) Successful in 35s
PR checks / java (pull_request) Successful in 1m15s
Main: tests, deploy, autotests / web (push) Successful in 31s
Main: tests, deploy, autotests / java (push) Successful in 1m15s
Main: tests, deploy, autotests / images-web (push) Successful in 34s
Main: tests, deploy, autotests / images-app (push) Successful in 43s
Main: tests, deploy, autotests / deploy (push) Successful in 1m41s
Main: tests, deploy, autotests / autotests (push) Successful in 35s
Main: tests, deploy, autotests / rollback (push) Has been skipped
docs(AGENTS): сжать до роутера без дублей, счётчики — в testing.md
2026-11-08 00:57:53 +00:00

14 lines
8.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
> читать при правке `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`, шрифты через `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`.