Диаграммы и SmartArt: пре-рендер w:drawing в PNG (pie, line, surface3D)

docx2fo.xslt умеет только a:graphicData/pic:pic — для c:chart и dgm:relIds
там notImplemented, т.е. объект молча исчезал из PDF. Новый internal/chart
рендерит их своим Java2D-движком в PNG 300 dpi и подменяет на pic:pic
(шаг 3.5 в convertToStream: после setFontMapper, до FOSettings).

surface3D: седловая ячейка режется диагональю с большей суммой значений
(верхняя огибающая седла). При фиксированной w00–w11 второй треугольник
становится невидимой щепкой, а видимая грань окрашивается не той полосой.
This commit is contained in:
Pjandro
2026-10-05 19:27:38 +00:00
parent 2d446d783c
commit 076975885c
21 changed files with 4360 additions and 0 deletions
+15
View File
@@ -29,6 +29,21 @@
- Пайплайн: байты docx → `DocxOnOffNormalizer` → docx4j → XSL-FO (XSLT) → FOP → PDF.
- Порядок инициализации в `WordPdfConverter.convertToStream` важен: сначала `new BundledFontMapper()`, потом `BundledFonts.init()` (бандл-шрифты регистрируются поверх системных), затем `BundledFonts.restrictToBundled()` (чистит реестр `PhysicalFonts` от системных шрифтов до `load()`; конструктор маппера каждый раз заново добавляет их, и `GlyphCheck` на Windows находит системный Calibri — em-dash остаётся на Carlito, красный `ruPlain_emDashEmbeddedNotHelvetica`). Не менять местами.
- docx4j 11.x теряет атрибуты `w:val="off"/"on"` при JAXB-разборе — поэтому нужна нормализация байтов до загрузки (регрессионный тест `ruPlain_regularRunsUseRegularFont`).
- Диаграммы: `docx2fo.xslt` умеет только `a:graphicData/pic:pic`, для `c:chart` и `dgm:relIds` там `notImplemented` (объект молча исчезает). Поэтому `DrawingPreRenderer.run(pkg)` (шаг 3.5 в `convertToStream`, после `setFontMapper` и до `FOSettings`) рендерит их своим Java2D-движком в PNG 300 dpi (`internal/chart/*`) и подменяет на `pic:pic`. Тест `chartsSmartArt_drawingsBecomeImages`, фикстура `samples/charts-smartart.docx`.
- В `DrawingPreRenderer` нужны собственные rels части — `part.getRelationshipsPart()` (`Base`), а **не** `getOwningRelationshipPart()`: у `document.xml` последнее указывает на пакетный `.rels`. Обход `pkg.getParts()` — только по снимку списка: `createImagePart` докидывает части в тот же реестр.
- SmartArt рисуется из `word/diagrams/drawing1.xml` (кэш разложенной Word-ом схемы: абсолютные позиции + `prstGeom`); текст-заполнители (`[Текст]`) лежат в `data1.xml` на `dgm:pt type="node"`, а формы ссылаются на `dgm:pt type="pres"` — связь через `dgm:cxn type="presOf"`.
- `surface3D` (`Surface3dPainter`): перспективная проекция (`c:view3D/perspective`, по умолчанию 30°, и `depth`), грани — ровно ячейки сетки по 2 треугольника без передискретизации, цвет из `c:bandFmts` затемняется по нормали грани (Lambert). Грани рисуются в модельно-экранных координатах уже умноженными на `scale/off` — забыть масштаб значит нарисовать поверхность в субпиксельный ноль.
- Знак `rotY` в DrawingML обратный правому правилу вокруг вертикали: в `Surface3dPainter.paint` он берётся как `-Math.toRadians(spec.rotY)`. Иначе передняя кромка категорий идёт вверх вправо, а ось рядов — вниз вправо (зеркально Word).
- `c:view3D/perspective` — НЕ угол обзора камеры. Расстояние камеры в `Surface3dPainter` = `CAMERA_DISTANCE * (30/perspective)`, где `CAMERA_DISTANCE = 2.36` (эффективный `fov ≈ 49°`, подобран фитом по эталону Word). При наивном `fov = perspective` перспектива слишком слабая: ось рядов уходит вправо вместо почти вертикального ухода в глубину, лента выглядит плоской, а левый край схлопывается в точку.
- Пропорции «коробки» surface3D (`DEPTH_RATIO = 0.705`, `HEIGHT_RATIO = 0.664`): глубина = 0.705 ширины (от неё `c:view3D/depth`), высота значений = `0.664 * availH/availW`, вписывание в область построения — равномерным масштабом. Раздельный масштаб x/y (или куб 1×1×1) даёт вертикальную гору вместо плоской ленты.
- Поля вокруг коробки — доли области построения `GUTTER_LEFT = GUTTER_RIGHT = 0.1485`, `GUTTER_TOP = 0.116`, `GUTTER_BOTTOM = 0.146`; `offX`/`offY` обязаны включать левое и верхнее поле (без `topGutter` поверхность сидела на 22 pt выше эталона). Коробка занимает ~70% ширины: при полях «на глаз» поверхность растягивалась на 82% и лезла на подписи оси значений.
- Калибровка камеры, коробки и полей зафиксирована тестами `Surface3dPainterTest.cameraMatchesWordReference` и `surfaceSilhouetteMatchesWordPlacement`. Эталон — стр. 3 `word-export.pdf` (экспорт Word), растеризованная `pdftoppm -r 300`; цели замеряются по **связному блоку граней** (серые грани в силуэт входят, по одной лишь насыщенности силуэт недомерен на 7%), пунктиру переднего ребра пола и подписям осей: уклон передней кромки 0,1282, аспект силуэта 0,207, шаг оси значений 0,0504, вертикальный шаг оси рядов 0,1176 (все — относительно ширины силуэта); сам силуэт 314,9×65,3 pt с центром в (227,3; 82,3). Замеры по скриншотам давали вдвое завышенную ось рядов и раздували глубину.
- Нормаль грани считается в той же метрике, что и проекция: `v` умножается на `depthScale`, `w` уже умножен на `hScale`. Без масштаба в нормали поверхность кажется положе и все грани уходят в светлую часть Lambert.
- Затенение граней surface3D — Lambert `0.92 + 0,88·dot` с клампом `[0,80; 1,25]` и боковым светом `LIGHT = (0,83, 0,48, 0,28)`. Дискретные множители эталона (гистограмма цветов граней, 300 dpi) — 0,40 / 0,75 / 0,85 / 1,04 / 1,06 / 1,10; группа 0,40 — узкая полоска underside под передним краем, и разгон Lambert до неё (отрицательные dot) по всем граням ухудшает совпадение с эталоном (17,2 → 17,6 средних расхождений на пиксель), поэтому нижний кламп 0,80. Направление света перебрано по 120 направлениям — текущее лучшее. Тест `shadingMatchesWordRange`.
- Триангуляция ячейки — диагональ с **большей суммой значений** (`z[r][c] + z[r+1][c+1] >= z[r+1][c] + z[r][c+1]` → `w00–w11`, иначе `w01–w10`), то есть верхняя огибающая седла. Фиксированная диагональ невозможна: у седловой ячейки одна вершина попадает внутрь треугольника остальных трёх, и при «не той» диагонали второй треугольник становится невидимой щепкой, а видимая грань окрашивается не той полосой. Проверено по эталону (стр. 3 `word-export.pdf`, 300 dpi, сравнение полос по пикселям; ячейка Ряд 1→2 / Категория 2→3): верхняя огибающая 92,3 % совпадений полос, фиксированная `w00–w11` — 81,6 %, фиксированная `w01–w10` — 57,9 %, окраска целого квада без разрезки — 74,1 %, билинейная tessellation 3×3/6×6 — 67,8 %/66,0 %. Регрессия — `Surface3dPainterTest.saddleCellUsesHigherDiagonal` (нижняя кромка силуэта в окне 0,42…0,55 его ширины обязана быть полосы 3–4). Клиппинг полос — по треугольникам, не по кваду.
- Пустой `c:title` при `c:autoTitleDeleted val="0"` даёт автозаголовок `Chart Title` (`ChartSpec.AUTO_TITLE`); для круговых (`pie`/`pie3D`/`doughnut`) вместо него — имя ряда. Тесты `ChartSpecTest`.
- В кваде ячейки `w01` обязан быть `z[r+1][c]`, а `w10` — `z[r][c+1]` (u=категория, v=ряд). Перестановка закручивает квад в «бабочку»: дыры и самопересечения граней.
- `ChartRenderer.axisBounds` для линейной оси значений без явного `c:min` всегда поднимает нижнюю границу до 0 (как Word); от этого зависит и легенда полос surface3D (`0-1 … 4-5`, а не `1-2 … 4-5`). Юнит-тесты — `Surface3dPainterTest`.
- Не убирать shade-фильтры `META-INF/*.SF|*.DSA|*.RSA` — подписанные jar-файлы зависимостей ломают fat-jar.
## Точка входа