@vvfx/svg2ir 0.0.0-stage → 0.0.1-beta.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +22 -0
- package/README.md +208 -2
- package/dist/common/errors.d.ts +33 -0
- package/dist/common/types.d.ts +93 -0
- package/dist/convert.d.ts +21 -0
- package/dist/debug.d.ts +8 -0
- package/dist/helper.d.ts +5 -0
- package/dist/index.d.ts +15 -0
- package/dist/index.js +17202 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +17196 -0
- package/dist/index.mjs.map +1 -0
- package/dist/node.d.ts +1 -0
- package/dist/node.js +17219 -0
- package/dist/node.js.map +1 -0
- package/dist/node.mjs +17213 -0
- package/dist/node.mjs.map +1 -0
- package/dist/parse-svg/bridge.d.ts +10 -0
- package/dist/parse-svg/build-element-tree-path.d.ts +2 -0
- package/dist/parse-svg/node.d.ts +3 -0
- package/dist/parse-svg/read-presentation-attribute.d.ts +5 -0
- package/dist/parse-svg/svg-parser.d.ts +46 -0
- package/dist/svg-preserved-data.d.ts +78 -0
- package/dist/svg-rasterizer/prepare-snapshot.d.ts +9 -0
- package/dist/svg-rasterizer/rasterize-svg.d.ts +11 -0
- package/dist/svg2ge-adapter/assemble.d.ts +5 -0
- package/dist/svg2ge-adapter/convert.d.ts +5 -0
- package/dist/svg2ge-adapter/converter/animation.d.ts +10 -0
- package/dist/svg2ge-adapter/converter/data-path.d.ts +6 -0
- package/dist/svg2ge-adapter/normalize-shape-animation.d.ts +2 -0
- package/dist/svg2ge-adapter/post-process/apply-fonts.d.ts +6 -0
- package/dist/svg2ge-adapter/post-process/apply-shape-geometry-animation.d.ts +4 -0
- package/dist/svg2ge-adapter/post-process/apply-shape-paint-animation.d.ts +4 -0
- package/dist/svg2ge-adapter/post-process/paint-animation-sampling.d.ts +13 -0
- package/dist/svg2ge-adapter/post-process/restore-gradient-uv.d.ts +3 -0
- package/dist/svg2ge-adapter/post-process/rewrite-text-components.d.ts +13 -0
- package/dist/svg2ge-adapter/pre-process.d.ts +7 -0
- package/dist/svg2ge-adapter/types.d.ts +11 -0
- package/dist/svg2ir/assemble.d.ts +11 -0
- package/dist/svg2ir/convert-arc.d.ts +10 -0
- package/dist/svg2ir/convert.d.ts +23 -0
- package/dist/svg2ir/converter/clip/apply-mask.d.ts +4 -0
- package/dist/svg2ir/converter/clip/build-clip-mask.d.ts +35 -0
- package/dist/svg2ir/converter/clip/collect-geometry.d.ts +32 -0
- package/dist/svg2ir/converter/clip/warn-unsupported.d.ts +7 -0
- package/dist/svg2ir/converter/diagnostics/collect-warnings.d.ts +6 -0
- package/dist/svg2ir/converter/diagnostics/inspect-filter.d.ts +4 -0
- package/dist/svg2ir/converter/diagnostics/warn-unsupported.d.ts +8 -0
- package/dist/svg2ir/converter/image/parse-image.d.ts +14 -0
- package/dist/svg2ir/converter/layers/build-layers.d.ts +8 -0
- package/dist/svg2ir/converter/layers/conversion-session.d.ts +163 -0
- package/dist/svg2ir/converter/layers/convert-group-element.d.ts +3 -0
- package/dist/svg2ir/converter/layers/convert-image-element.d.ts +3 -0
- package/dist/svg2ir/converter/layers/convert-shape-element.d.ts +3 -0
- package/dist/svg2ir/converter/layers/convert-text-element.d.ts +3 -0
- package/dist/svg2ir/converter/layers/convert-use-element.d.ts +3 -0
- package/dist/svg2ir/converter/layers/element-categories.d.ts +2 -0
- package/dist/svg2ir/converter/layers/registry.d.ts +4 -0
- package/dist/svg2ir/converter/paint/resolve-gradient.d.ts +29 -0
- package/dist/svg2ir/converter/shape/convert-annulus.d.ts +10 -0
- package/dist/svg2ir/converter/shape/parse-dash.d.ts +23 -0
- package/dist/svg2ir/converter/shape/parse-shape-element.d.ts +4 -0
- package/dist/svg2ir/converter/shape/parse-shape-primitives.d.ts +15 -0
- package/dist/svg2ir/converter/smil/apply-opacity-composition.d.ts +6 -0
- package/dist/svg2ir/converter/smil/apply-transform-animation.d.ts +14 -0
- package/dist/svg2ir/converter/smil/apply-transform-composition.d.ts +4 -0
- package/dist/svg2ir/converter/smil/build-keyframes.d.ts +10 -0
- package/dist/svg2ir/converter/smil/collect-geometry-animation.d.ts +7 -0
- package/dist/svg2ir/converter/smil/inspect-animation.d.ts +6 -0
- package/dist/svg2ir/converter/smil/parse-motion.d.ts +4 -0
- package/dist/svg2ir/converter/smil/parse-paint-animation.d.ts +13 -0
- package/dist/svg2ir/converter/smil/parse-shape-animation.d.ts +4 -0
- package/dist/svg2ir/converter/smil/parse-timeline.d.ts +4 -0
- package/dist/svg2ir/converter/smil/resolve-animation-target.d.ts +4 -0
- package/dist/svg2ir/converter/smil/sample-composition-frames.d.ts +42 -0
- package/dist/svg2ir/converter/smil/scan-duration.d.ts +4 -0
- package/dist/svg2ir/converter/smil/timeline-schedule.d.ts +17 -0
- package/dist/svg2ir/converter/smil/timeline-values.d.ts +20 -0
- package/dist/svg2ir/converter/smil/types.d.ts +129 -0
- package/dist/svg2ir/converter/switch-branch.d.ts +3 -0
- package/dist/svg2ir/converter/text/build-per-line-text-layers.d.ts +11 -0
- package/dist/svg2ir/converter/text/build-single-text-layer.d.ts +11 -0
- package/dist/svg2ir/converter/text/build-split-text-layers.d.ts +11 -0
- package/dist/svg2ir/converter/text/build-vertical-text-layers.d.ts +10 -0
- package/dist/svg2ir/converter/text/font-metrics.d.ts +55 -0
- package/dist/svg2ir/converter/text/inspect-content.d.ts +42 -0
- package/dist/svg2ir/converter/text/parse.d.ts +10 -0
- package/dist/svg2ir/converter/text/text-layout.d.ts +29 -0
- package/dist/svg2ir/converter/transform/build-transform.d.ts +15 -0
- package/dist/svg2ir/converter/use/collect-group-use-instances.d.ts +16 -0
- package/dist/svg2ir/converter/use/expand-use.d.ts +31 -0
- package/dist/svg2ir/css-named-colors.d.ts +1 -0
- package/dist/svg2ir/index.d.ts +2 -0
- package/dist/svg2ir/map-color.d.ts +3 -0
- package/dist/svg2ir/matrix.d.ts +67 -0
- package/dist/svg2ir/normalize-path.d.ts +52 -0
- package/dist/svg2ir/read-attributes.d.ts +12 -0
- package/dist/svg2layers-adapter/assemble.d.ts +21 -0
- package/dist/svg2layers-adapter/baking/build-baked-layers.d.ts +13 -0
- package/dist/svg2layers-adapter/baking/normalize-layer-blending.d.ts +10 -0
- package/dist/svg2layers-adapter/baking/plan-graphic-baking.d.ts +18 -0
- package/dist/svg2layers-adapter/baking/resolve-baking-warnings.d.ts +4 -0
- package/dist/svg2layers-adapter/convert.d.ts +4 -0
- package/dist/svg2layers-adapter/converter/diagnostics/collect-warnings.d.ts +10 -0
- package/dist/svg2layers-adapter/converter/image/convert-image-layer.d.ts +5 -0
- package/dist/svg2layers-adapter/converter/image/inspect-mask.d.ts +3 -0
- package/dist/svg2layers-adapter/converter/layers/build-layers.d.ts +3 -0
- package/dist/svg2layers-adapter/converter/layers/conversion-session.d.ts +14 -0
- package/dist/svg2layers-adapter/converter/layers/registry.d.ts +9 -0
- package/dist/svg2layers-adapter/converter/layers/resolve-visual-state.d.ts +4 -0
- package/dist/svg2layers-adapter/converter/text/convert-text-layer.d.ts +5 -0
- package/dist/svg2layers-adapter/converter/text/parse-text-runs.d.ts +11 -0
- package/dist/svg2layers-adapter/converter/text/text-layout.d.ts +9 -0
- package/dist/svg2layers-adapter/converter/transform/build-transform.d.ts +8 -0
- package/dist/svg2layers-adapter/matrix.d.ts +16 -0
- package/dist/svg2layers-adapter/post-process/inline-image-resources.d.ts +3 -0
- package/dist/svg2layers-adapter/strip-layer-animation.d.ts +5 -0
- package/dist/svg2layers-adapter/types.d.ts +61 -0
- package/package.json +61 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT LICENSE
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2019-present Ant Group Co., Ltd. https://www.antgroup.com/
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
|
6
|
+
a copy of this software and associated documentation files (the
|
|
7
|
+
"Software"), to deal in the Software without restriction, including
|
|
8
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
|
9
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
|
10
|
+
permit persons to whom the Software is furnished to do so, subject to
|
|
11
|
+
the following conditions:
|
|
12
|
+
|
|
13
|
+
The above copyright notice and this permission notice shall be
|
|
14
|
+
included in all copies or substantial portions of the Software.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
17
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
18
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
19
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
|
20
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
|
21
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
|
22
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,209 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @vvfx/svg2ir
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
English | [简体中文](./README-zh_CN.md)
|
|
4
|
+
|
|
5
|
+
Convert SVG into source-neutral Animation IR, with optional SVG-to-GE and SVG-to-layers adapters in the same package.
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
## Contents
|
|
9
|
+
|
|
10
|
+
- [Install](#install)
|
|
11
|
+
- [Usage](#usage)
|
|
12
|
+
- [API](#api)
|
|
13
|
+
- [Output](#output)
|
|
14
|
+
- [Input capabilities](#input-capabilities)
|
|
15
|
+
- [Limitations](#limitations)
|
|
16
|
+
- [License](#license)
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
pnpm add @vvfx/svg2ir @vvfx/ge-ir
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Node.js 22 or later and pnpm 10 or later are required. Browser and Node callers use the same root import; the Node
|
|
25
|
+
conditional entry automatically supplies the `svgdom` parsing base.
|
|
26
|
+
|
|
27
|
+
## Usage
|
|
28
|
+
|
|
29
|
+
### SVG to IR
|
|
30
|
+
|
|
31
|
+
```ts
|
|
32
|
+
import { convertSVGToIR } from '@vvfx/svg2ir';
|
|
33
|
+
|
|
34
|
+
const { ir, warnings } = convertSVGToIR(
|
|
35
|
+
'<svg width="400" height="300"><rect x="20" y="20" width="200" height="120" fill="#1677ff"/></svg>',
|
|
36
|
+
);
|
|
37
|
+
|
|
38
|
+
console.info(ir.compositions[0].layers, warnings);
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
`convertSVGToIR` returns the core `IRScene` and warnings. SVG-specific preserved data is not included.
|
|
42
|
+
|
|
43
|
+
### Preserve SVG-specific data
|
|
44
|
+
|
|
45
|
+
```ts
|
|
46
|
+
import { splitSVG } from '@vvfx/svg2ir';
|
|
47
|
+
|
|
48
|
+
const { ir, warnings, preservedData } = splitSVG(svgSource);
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`preservedData` is an `SVGPreservedData` sidecar for information that the core IR cannot represent, including rich
|
|
52
|
+
text spans and SMIL paint animation. Static layers export also uses the preserved text spans.
|
|
53
|
+
|
|
54
|
+
### SVG to GE
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
import { convertSVGToGE, splitSVG } from '@vvfx/svg2ir';
|
|
58
|
+
|
|
59
|
+
const split = splitSVG(svgSource);
|
|
60
|
+
const { data, warnings } = convertSVGToGE(
|
|
61
|
+
svgSource,
|
|
62
|
+
{ fonts: [{ fontFamily: 'Custom Sans', fontURL: 'https://example.com/fonts/custom-sans.woff2' }] },
|
|
63
|
+
split.preservedData,
|
|
64
|
+
);
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`convertSVGToGE` uses `@vvfx/ge-ir` to build the base scene. Passing the sidecar enables SVG-specific rich-text,
|
|
68
|
+
paint-animation, and gradient-UV post-processing. Font definitions are supplied independently through `fonts`.
|
|
69
|
+
|
|
70
|
+
### SVG to static layers
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
import { convertSVG } from '@vvfx/svg2ir';
|
|
74
|
+
|
|
75
|
+
const svgSource = '<svg width="400" height="300"><text x="20" y="40" font-size="24">Hello</text></svg>';
|
|
76
|
+
const { size: canvasSize, data: layers, warnings } = await convertSVG(svgSource, { outputFormat: 'layers' });
|
|
77
|
+
const json = JSON.stringify(layers);
|
|
78
|
+
|
|
79
|
+
console.info(canvasSize, json, warnings);
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
With `outputFormat: 'layers'`, `convertSVG` converts Animation IR and SVG preserved text data directly into
|
|
83
|
+
static layers and asynchronously returns `{ size, data, warnings }`.
|
|
84
|
+
`data` is a flat array of image and text layers; `size` is the separate canvas width and height in pixels.
|
|
85
|
+
SVG images become image layers, and native text becomes editable text layers. Text inside images is not recognized.
|
|
86
|
+
|
|
87
|
+
Self-contained static graphics are baked into transparent PNG layers, preserving fills, gradients,
|
|
88
|
+
patterns, strokes, markers, transforms, filters, clipping, masks, and opacity. Ordinary graphics stay separate;
|
|
89
|
+
group-wide effects may merge child graphics into one PNG. Native text and images are never baked.
|
|
90
|
+
Consumers must create layers in array order to retain SVG painter order.
|
|
91
|
+
|
|
92
|
+
Non-normal blend modes (such as multiply, screen, and overlay) are downgraded to normal alpha compositing.
|
|
93
|
+
Baking and downgrades produce warnings; successful baking remains advisory in strict mode.
|
|
94
|
+
Baking requires browser SVG, Canvas, and DOM support; Node converts native layers and warns for unbaked graphics.
|
|
95
|
+
Mixed native effect groups, dependencies containing text/images, external paint resources, animations, scripts,
|
|
96
|
+
and `foreignObject` are not baked.
|
|
97
|
+
|
|
98
|
+
Layer format:
|
|
99
|
+
|
|
100
|
+
- Common fields: `id` is generated automatically; `bbox` uses canvas-pixel coordinates
|
|
101
|
+
`[left, top, right, bottom]`. Native geometry is rounded to two decimal places.
|
|
102
|
+
- Image layers: `type: 'image'`, `role: 'content'`, and a Base64 data URL in `url`.
|
|
103
|
+
`size` holds display dimensions before rotation; `rotation` holds XYZ Euler angles in degrees (positive Z is
|
|
104
|
+
clockwise). `width` and `height` are the bbox dimensions.
|
|
105
|
+
Baked geometry follows raster resolution; transforms are included in the pixels, with `rotation: [0, 0, 0]`.
|
|
106
|
+
- Text layers: `type: 'text'`, `state: 'active'`, full text in `content`, and `fragments` containing text runs,
|
|
107
|
+
fonts, sizes, colors, and spacing. Fragment `bbox` and `polygon` are relative to the text layer's top-left corner;
|
|
108
|
+
polygon contains the layout corners. Rotation uses degrees and colors use `#RRGGBB`.
|
|
109
|
+
Native text requires no image erasure, so `erase_operations` is empty.
|
|
110
|
+
|
|
111
|
+
External images are fetched and inlined; browser fetch requires CORS. Supply `loadImage` for local files or
|
|
112
|
+
authenticated resources and `resourceBaseUrl` for relative image references. Failed reads or invalid resources throw errors.
|
|
113
|
+
|
|
114
|
+
## API
|
|
115
|
+
|
|
116
|
+
### Package API
|
|
117
|
+
|
|
118
|
+
- `convertSVGToIR(source, options?)` returns `{ ir, warnings }`.
|
|
119
|
+
- `splitSVG(source, options?)` returns `{ ir, warnings, preservedData }`.
|
|
120
|
+
- `convertSVGToGE(source, options?, preservedData?)` returns `{ data, warnings }`.
|
|
121
|
+
- `convertSVG(source, options?, preservedData?)` returns `{ data, warnings }` synchronously for GE, or
|
|
122
|
+
`Promise<SVGToLayersResult>` for layers.
|
|
123
|
+
- `inferNumericWeightFromFamily(fontFamily)` infers a numeric font weight, or returns `null`.
|
|
124
|
+
|
|
125
|
+
Important options include `frameRate` (default `30`), `durationSeconds` (default `5` for static SVG),
|
|
126
|
+
`backgroundColor`, `resourceBaseUrl`, `imageNaturalSizes`, `measureText`, `strict`, `onWarning`, and the GE-only
|
|
127
|
+
`fonts` list. `resourceBaseUrl` must be absolute when used to resolve relative image references.
|
|
128
|
+
`convertSVG` also accepts `outputFormat` (`'ge'` by default or `'layers'`) and a layers-only `loadImage` callback:
|
|
129
|
+
`(url) => Promise<{ data: Uint8Array; mimeType: string }>`; `data` contains the original image bytes.
|
|
130
|
+
|
|
131
|
+
The layers-only `rasterScale` option controls PNG resolution without changing display size; it defaults to `2`
|
|
132
|
+
and must be finite and positive. The working raster is limited to 16 megapixels.
|
|
133
|
+
|
|
134
|
+
All public types, including `SVGPreservedData`, `ConvertOptions`, `SVGToGEOptions`, `SVGToLayersOptions`, `SVGStaticLayer`,
|
|
135
|
+
`SVG2IRWarning`, and result types, are exported from `@vvfx/svg2ir`.
|
|
136
|
+
|
|
137
|
+
## Output
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
convertSVGToIR(source, options?);
|
|
141
|
+
// { ir: IRScene; warnings: SVG2IRWarning[] }
|
|
142
|
+
|
|
143
|
+
splitSVG(source, options?);
|
|
144
|
+
// { ir: IRScene; warnings: SVG2IRWarning[]; preservedData: SVGPreservedData }
|
|
145
|
+
|
|
146
|
+
convertSVGToGE(source, options?, preservedData?);
|
|
147
|
+
// { data: JSONScene; warnings: SVG2IRWarning[] }
|
|
148
|
+
|
|
149
|
+
await convertSVG(source, { outputFormat: 'layers' });
|
|
150
|
+
// { size: [number, number]; data: SVGStaticLayer[]; warnings: SVG2IRWarning[] }
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## Input capabilities
|
|
154
|
+
|
|
155
|
+
Supported refers to the listed subset; partial means some attributes are approximated or omitted. Output format
|
|
156
|
+
matters: static layers support a smaller subset than IR and GE.
|
|
157
|
+
|
|
158
|
+
### IR and GE
|
|
159
|
+
|
|
160
|
+
| Capability | Status | Behavior |
|
|
161
|
+
| --- | --- | --- |
|
|
162
|
+
| SVG string and shapes | Supported | `rect`, `circle`, `ellipse`, `path`, `polygon`, `polyline`, and `line`. |
|
|
163
|
+
| Groups and references | Supported | Hierarchy, transforms, opacity, and expanded `use` / `symbol` instances. |
|
|
164
|
+
| Images | Partial | URL assets and aspect ratio; supply natural sizes to avoid fitted-geometry fallback. |
|
|
165
|
+
| Text | Partial | Text/tspan, text paths, multiline and vertical text; GE rich text needs the sidecar. |
|
|
166
|
+
| Paints | Partial | Solid and supported gradients; gradient text is flattened, some gradient attributes lost. |
|
|
167
|
+
| Masks and clip paths | Partial | Element clip paths and element/group masks; unit and region limits below. |
|
|
168
|
+
| Group `clip-path` | Unsupported | Omitted with `svg2ir_group_clip_path_dropped`. |
|
|
169
|
+
| SMIL | Partial | Transform, motion, opacity, visibility, selected geometry and paint; GE paint uses sidecar. |
|
|
170
|
+
| Filters / patterns / markers | Unsupported | Effects omitted with warnings; supported content remains. |
|
|
171
|
+
| Skew and text decoration | Unsupported | Dropped with warnings; text stroke is also omitted. |
|
|
172
|
+
| Other elements | Unsupported | Unmapped content such as `foreignObject` is omitted with warnings. |
|
|
173
|
+
|
|
174
|
+
### Static layers
|
|
175
|
+
|
|
176
|
+
| Capability | Status | Behavior |
|
|
177
|
+
| --- | --- | --- |
|
|
178
|
+
| Images and native text | Supported | Flat image/text layers; text inside images is not recognized. |
|
|
179
|
+
| Image resources | Supported | Fetches and inlines bytes; use `loadImage` for local or authenticated resources. |
|
|
180
|
+
| Text layout and styles | Partial | Metrics may be estimated; bold/italic are downgraded; vertical text is split. |
|
|
181
|
+
| Shapes and animation | Unsupported | Skipped with warnings; layers export does not rasterize vector shapes. |
|
|
182
|
+
| Masks and visual transforms | Partial | Basic rotation/scale; unsupported opacity, crop, skew, etc. skip layers. |
|
|
183
|
+
|
|
184
|
+
Read `warnings` and optionally `onWarning`. Examples include `svg2ir_filter_dropped`,
|
|
185
|
+
`svg2ir_text_gradient_fill_flattened`, and `svg2ge_layers_unsupported_feature`.
|
|
186
|
+
`strict: true` rejects reported unsupported features and style downgrades; estimated layer text bounds still warn.
|
|
187
|
+
Invalid SVG and failed layer image loads throw errors. An empty warning list is not a complete rendering-fidelity check.
|
|
188
|
+
|
|
189
|
+
## Limitations
|
|
190
|
+
|
|
191
|
+
- Filters, patterns, markers, skew, and some text decoration are downgraded or reported as warnings.
|
|
192
|
+
- Element-level projection, blur, and inner-shadow effects do not have a general GE Runtime representation.
|
|
193
|
+
- Rich text cannot preserve every text stroke, decoration, or per-span position.
|
|
194
|
+
- Some radial-gradient focal offsets, `spreadMethod`, and `gradientTransform` values are not retained.
|
|
195
|
+
- Group-level `clip-path` is not currently mapped; element clip paths and group masks are supported.
|
|
196
|
+
- IR and GE conversion do not download external resources. Callers own URL resolution, font loading, and runtime
|
|
197
|
+
resource access. Layers export reads and inlines image resources as described above.
|
|
198
|
+
|
|
199
|
+
Static layers export supports images and text only. SMIL animation elements are removed with a warning; unsupported animated channels, unbaked shapes, solid backgrounds,
|
|
200
|
+
image skew/reflection/cropping, masks, opacity, nonuniform text scaling, and text paths are skipped with warnings.
|
|
201
|
+
Bold and italic styles are downgraded with warnings; vertical text is split into character layers with horizontal fragments.
|
|
202
|
+
Supply `measureText` for font metrics; incomplete metrics produce estimated bounds and warnings.
|
|
203
|
+
`strict: true` turns unsupported content and style downgrades into errors; estimated bounds still produce warnings.
|
|
204
|
+
|
|
205
|
+
Images are retained when a straight rectangular mask covers the full image without inversion or subtraction.
|
|
206
|
+
|
|
207
|
+
## License
|
|
208
|
+
|
|
209
|
+
[MIT](./LICENSE) © 2019-present Ant Group Co., Ltd.
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* svg2ir 内部转换错误码常量。
|
|
3
|
+
*
|
|
4
|
+
* 内部转换阶段使用这些常量区分失败阶段,避免依赖 message 文本。
|
|
5
|
+
*
|
|
6
|
+
* 转换器遇到不可继续的错误(解析失败/IR 校验失败/生成失败)抛内部转换错误;
|
|
7
|
+
* 可丢降级的特性走 warnings,不抛错。
|
|
8
|
+
*/
|
|
9
|
+
/** svg2ir 内部转换错误码,裸字符串(不带包名前缀)。 */
|
|
10
|
+
export declare const SVG_CONVERTER_ERROR_CODES: {
|
|
11
|
+
/** SVG 串/资源无法解析为合法 SVG DOM。 */
|
|
12
|
+
readonly INVALID_SVG: "INVALID_SVG";
|
|
13
|
+
readonly LAYERS_CONVERSION_FAILED: "LAYERS_CONVERSION_FAILED";
|
|
14
|
+
/** SVG 解析底座(reader/reader)初始化失败。 */
|
|
15
|
+
readonly PARSE_FAIL: "PARSE_FAIL";
|
|
16
|
+
/** IR 结构校验失败(animation-ir 内部 IR_xxx 映射到该码)。 */
|
|
17
|
+
readonly IR_VALIDATION_FAILED: "IR_VALIDATION_FAILED";
|
|
18
|
+
};
|
|
19
|
+
export type SVGConverterErrorCode = (typeof SVG_CONVERTER_ERROR_CODES)[keyof typeof SVG_CONVERTER_ERROR_CODES];
|
|
20
|
+
/**
|
|
21
|
+
* 判断输入值是否为 {@link SVGConverterErrorCode}。
|
|
22
|
+
*/
|
|
23
|
+
export declare function isSVGConverterErrorCode(code: unknown): code is SVGConverterErrorCode;
|
|
24
|
+
/** svg2ir 内部统一错误类型。 */
|
|
25
|
+
export declare class SVGConverterError extends Error {
|
|
26
|
+
readonly code: SVGConverterErrorCode;
|
|
27
|
+
readonly details?: Record<string, unknown>;
|
|
28
|
+
constructor(code: SVGConverterErrorCode, message: string, details?: Record<string, unknown>);
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* 将任意异常标准化为 {@link SVGConverterError},并尽量保留内部错误码与上下文。
|
|
32
|
+
*/
|
|
33
|
+
export declare function normalizeToConverterError(error: unknown, fallbackCode: SVGConverterErrorCode, fallbackMessage: string, details?: Record<string, unknown>): SVGConverterError;
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import type { IRScene } from '@vvfx/animation-ir';
|
|
2
|
+
/** SVG 字符串。convertSVGToIR 的输入。 */
|
|
3
|
+
export type SVGSource = string;
|
|
4
|
+
/** SVG → Animation IR 转换选项。 */
|
|
5
|
+
export interface ConvertOptions {
|
|
6
|
+
/** 画布帧率,决定 IR 帧时间。默认 30。 */
|
|
7
|
+
frameRate?: number;
|
|
8
|
+
/** 静态 SVG 的展示时长(秒)。动态 SVG 可由 SMIL active interval 覆盖。默认 5。 */
|
|
9
|
+
durationSeconds?: number;
|
|
10
|
+
/** 输出 IR composition 的画布底色;未传时保持透明。支持 SVG 颜色字符串。 */
|
|
11
|
+
backgroundColor?: string | null;
|
|
12
|
+
/** true 时遇到无法表达的元素中断转换;false(默认)记录 warning 并继续。 */
|
|
13
|
+
strict?: boolean;
|
|
14
|
+
/** warning 回调:每条 warning 会先进入 ConvertResult.warnings,再通知调用方。 */
|
|
15
|
+
onWarning?: (warning: SVG2IRWarning) => void;
|
|
16
|
+
/** 可选的文本测量回调,用于改进 SVG 文本几何的 IR bounds。 */
|
|
17
|
+
measureText?: (fontDesc: string, text: string) => {
|
|
18
|
+
width: number;
|
|
19
|
+
fontBoundingBoxAscent?: number;
|
|
20
|
+
fontBoundingBoxDescent?: number;
|
|
21
|
+
actualBoundingBoxAscent?: number;
|
|
22
|
+
hangingBaseline?: number;
|
|
23
|
+
};
|
|
24
|
+
/** SVG 来源的绝对 URL,用于把相对图片 href 解析为规范化 IR Asset URL。 */
|
|
25
|
+
resourceBaseUrl?: string;
|
|
26
|
+
/** 图片 intrinsic(自然)尺寸表,url→{width,height}。用于算 <image> 默认 preserveAspectRatio="xMidYMid meet"
|
|
27
|
+
* 的 fitted 几何框(svg2ir 不下载图、Node/svgdom 无 HTMLImageElement,自己拿不到自然尺寸)。浏览器调用方通常
|
|
28
|
+
* 走 inlineSvgImages 给 <image> 盖 data-natural-w/h(优先于此表);Node 调用方读 PNG/JPEG 文件头建此表
|
|
29
|
+
* 传入。两者都无时,meet 使用 full-fit 拉伸。key 用 <image> href 原值(xlink:href/href/dataURI)。 */
|
|
30
|
+
imageNaturalSizes?: Map<string, {
|
|
31
|
+
width: number;
|
|
32
|
+
height: number;
|
|
33
|
+
}>;
|
|
34
|
+
}
|
|
35
|
+
/** SVG 转换产出。 */
|
|
36
|
+
export interface ConvertResult {
|
|
37
|
+
/** SVG 解析后的完整 IRScene。 */
|
|
38
|
+
ir: IRScene;
|
|
39
|
+
/** 转换过程丢弃/降级的特性列表。 */
|
|
40
|
+
warnings: SVG2IRWarning[];
|
|
41
|
+
}
|
|
42
|
+
/** 转换过程中产生的烘焙、降级或内容损失诊断。 */
|
|
43
|
+
export interface SVG2IRWarning {
|
|
44
|
+
code: SVG2IRWarningCode;
|
|
45
|
+
message: string;
|
|
46
|
+
/** 触发元素在 SVG 里的定位提示(id/tag/索引等)。 */
|
|
47
|
+
elementSelector?: string;
|
|
48
|
+
}
|
|
49
|
+
/** SVG 转换诊断码;用于报告烘焙、降级和不支持的特性。 */
|
|
50
|
+
export declare const SVG2IR_WARNING_CODES: {
|
|
51
|
+
/** 图形或图形组已栅格化,矢量编辑能力变化通过 warning 报告。 */
|
|
52
|
+
readonly LAYERS_GRAPHIC_BAKED: "svg2ge_layers_graphic_baked";
|
|
53
|
+
readonly LAYERS_BLEND_MODE_DOWNGRADED: "svg2ge_layers_blend_mode_downgraded";
|
|
54
|
+
readonly LAYERS_ANIMATION_STRIPPED: "svg2ge_layers_animation_stripped";
|
|
55
|
+
readonly LAYERS_UNSUPPORTED_TYPE: "svg2ge_layers_unsupported_type";
|
|
56
|
+
readonly LAYERS_UNSUPPORTED_FEATURE: "svg2ge_layers_unsupported_feature";
|
|
57
|
+
readonly LAYERS_INVALID_DATA: "svg2ge_layers_invalid_data";
|
|
58
|
+
readonly LAYERS_TEXT_STYLE_DROPPED: "svg2ge_layers_text_style_dropped";
|
|
59
|
+
readonly LAYERS_TEXT_BOUNDS_ESTIMATED: "svg2ge_layers_text_bounds_estimated";
|
|
60
|
+
/** 元素整体不渲染也不映射(无法展开的 use、foreignObject、switch 等不支持元素)。 */
|
|
61
|
+
readonly ELEMENT_DROPPED: "svg2ir_element_dropped";
|
|
62
|
+
/** stroke-dasharray/dashoffset 无法完整写入当前 IR,按可表达子集处理。 */
|
|
63
|
+
readonly STROKE_DASH_DROPPED: "svg2ir_stroke_dash_dropped";
|
|
64
|
+
/** SVG filter(feGaussianBlur 等)没有对应 IR 字段。 */
|
|
65
|
+
readonly FILTER_DROPPED: "svg2ir_filter_dropped";
|
|
66
|
+
/** pattern 平铺填充没有对应 IR paint。 */
|
|
67
|
+
readonly PATTERN_DROPPED: "svg2ir_pattern_dropped";
|
|
68
|
+
/** skewX/skewY 没有对应 IR transform 通道。 */
|
|
69
|
+
readonly SKEW_DROPPED: "svg2ir_skew_dropped";
|
|
70
|
+
/** IRTextContent 只有单色文本填充,渐变文字按中点色处理。 */
|
|
71
|
+
readonly TEXT_GRADIENT_FILL_FLATTENED: "svg2ir_text_gradient_fill_flattened";
|
|
72
|
+
/** IRTextContent 没有文本描边字段。 */
|
|
73
|
+
readonly TEXT_STROKE_DROPPED: "svg2ir_text_stroke_dropped";
|
|
74
|
+
/** IRTextContent 没有 text-decoration 字段。 */
|
|
75
|
+
readonly TEXT_DECORATION_DROPPED: "svg2ir_text_decoration_dropped";
|
|
76
|
+
/** Effects adapter 未获得调用方提供的字体文件,运行时可能使用 fallback。 */
|
|
77
|
+
readonly TEXT_FONT_NOT_SUPPLIED: "svg2ir_text_font_not_supplied";
|
|
78
|
+
/** ge-ir 导出阶段报告了规范化或保真降级。 */
|
|
79
|
+
readonly GE_EXPORT_DIAGNOSTIC: "svg2ir_ge_export_diagnostic";
|
|
80
|
+
/** clipPathUnits=objectBoundingBox:裁剪实现只接受 userSpaceOnUse。 */
|
|
81
|
+
readonly CLIP_PATH_UNITS_DROPPED: "svg2ir_clip_path_units_dropped";
|
|
82
|
+
/** clipPath 内显式 clip-rule/fill-rule 没有对应 IR mask 规则字段。 */
|
|
83
|
+
readonly CLIP_RULE_DROPPED: "svg2ir_clip_rule_dropped";
|
|
84
|
+
/** <g clip-path> 组级裁剪:当前仅支持元素级 clip-path 与组级 mask。 */
|
|
85
|
+
readonly GROUP_CLIP_PATH_DROPPED: "svg2ir_group_clip_path_dropped";
|
|
86
|
+
/** maskContentUnits=objectBoundingBox:mask 几何只接受 userSpaceOnUse。 */
|
|
87
|
+
readonly MASK_CONTENT_UNITS_DROPPED: "svg2ir_mask_content_units_dropped";
|
|
88
|
+
/** maskUnits / x/y/width/height 没有对应 IR mask region 字段。 */
|
|
89
|
+
readonly MASK_REGION_DROPPED: "svg2ir_mask_region_dropped";
|
|
90
|
+
/** mask-type=luminance/alpha:当前 IR mask 不保留该模式。 */
|
|
91
|
+
readonly MASK_TYPE_DROPPED: "svg2ir_mask_type_dropped";
|
|
92
|
+
};
|
|
93
|
+
export type SVG2IRWarningCode = (typeof SVG2IR_WARNING_CODES)[keyof typeof SVG2IR_WARNING_CODES];
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { ConvertOptions, SVGSource } from './common/types';
|
|
2
|
+
import type { SVGPreservedData } from './svg-preserved-data';
|
|
3
|
+
import type { SVGImageResourceLoader, SVGToLayersResult } from './svg2layers-adapter/types';
|
|
4
|
+
import type { SVGToGEOptions, SVGToGEResult } from './svg2ge-adapter/types';
|
|
5
|
+
export interface SVGConversionOptions extends ConvertOptions {
|
|
6
|
+
outputFormat?: 'ge' | 'layers';
|
|
7
|
+
fonts?: SVGToGEOptions['fonts'];
|
|
8
|
+
/** layers 图片读取回调;默认使用 fetch,已有 data URL 无需读取。 */
|
|
9
|
+
loadImage?: SVGImageResourceLoader;
|
|
10
|
+
/** Graphic baking resolution; logical layer dimensions remain unchanged. Default: 2. */
|
|
11
|
+
rasterScale?: number;
|
|
12
|
+
}
|
|
13
|
+
export interface SVGToLayersOptions extends SVGConversionOptions {
|
|
14
|
+
outputFormat: 'layers';
|
|
15
|
+
}
|
|
16
|
+
/** SVG 多格式输出入口,默认返回 GE 场景。 */
|
|
17
|
+
export declare function convertSVG(source: SVGSource, options: SVGToLayersOptions, preservedData?: SVGPreservedData): Promise<SVGToLayersResult>;
|
|
18
|
+
export declare function convertSVG(source: SVGSource, options?: SVGToGEOptions & {
|
|
19
|
+
outputFormat?: 'ge';
|
|
20
|
+
}, preservedData?: SVGPreservedData): SVGToGEResult;
|
|
21
|
+
export declare function convertSVG(source: SVGSource, options?: SVGConversionOptions, preservedData?: SVGPreservedData): SVGToGEResult | Promise<SVGToLayersResult>;
|
package/dist/debug.d.ts
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* 内部调试入口,不属于稳定 API。
|
|
3
|
+
*
|
|
4
|
+
* 仅供仓库内 parser、validation 和错误排障使用。
|
|
5
|
+
*/
|
|
6
|
+
export { parseSVGToIRScene } from './svg2ir';
|
|
7
|
+
export { SVGConverterError, SVG_CONVERTER_ERROR_CODES, isSVGConverterErrorCode, normalizeToConverterError, } from './common/errors';
|
|
8
|
+
export type { SVGConverterErrorCode } from './common/errors';
|
package/dist/helper.d.ts
ADDED
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @vvfx/svg2ir — SVG → Animation IR / Effects 转换引擎。
|
|
3
|
+
*
|
|
4
|
+
* 根入口提供 SVG→IR、SVG 保留数据拆分及 GE/静态分层输出。
|
|
5
|
+
*/
|
|
6
|
+
export { convertSVGToIR, splitSVG } from './svg2ir/convert';
|
|
7
|
+
export { convertSVG } from './convert';
|
|
8
|
+
export { convertSVGToGE } from './svg2ge-adapter/convert';
|
|
9
|
+
export type { ConvertOptions, ConvertResult, SVG2IRWarning, SVG2IRWarningCode, SVGSource, } from './common/types';
|
|
10
|
+
export type { SplitSVGOptions, SplitSVGResult } from './svg2ir/convert';
|
|
11
|
+
export type { SVGToGEOptions, SVGToGEResult } from './svg2ge-adapter/types';
|
|
12
|
+
export type { SVGConversionOptions, SVGToLayersOptions } from './convert';
|
|
13
|
+
export type { SVGPreservedData, SVGFontDefinition, SVGPreservedPaintAnimation, SVGPreservedShapeAnimation, SVGPreservedTextData, SVGPreservedTextSpan, } from './svg-preserved-data';
|
|
14
|
+
export type { SVGStaticLayer, SVGImageLayer, SVGTextLayer, SVGTextFragment, SVGLayerBBox, SVGToLayersResult, SVGLayerEraseOperation, SVGImageResource, SVGImageResourceLoader, } from './svg2layers-adapter/types';
|
|
15
|
+
export { inferNumericWeightFromFamily } from './svg2ir/converter/text/font-metrics';
|