@vvfx/ge-ir 0.0.1-beat.2

package/LICENSE

@@ -0,0 +1,22 @@
+MIT LICENSE
+
+Copyright (c) 2019-present Ant Group Co., Ltd. https://www.antgroup.com/
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @vvfx/ge-ir
+
+> 内部转换包。统一承载 Galacean Effects JSONScene 与 `@vvfx/animation-ir`
+> 之间的双向转换能力，供 monorepo 内的 `lottie2ge`、`dsl2ge`、调试页面等链路复用。
+
+## 能力范围
+
+```
+JSONScene ── convertGEToIR ──> IRComposition ── convertIRToGE ──> JSONScene
+                         @vvfx/animation-ir
+```
+
+本包不定义 IR 数据模型；`@vvfx/animation-ir` 仍是 IR 类型和校验逻辑的唯一真源。
+
+## 主要 API
+
+```ts
+import { convertGEToIR, convertIRToGE } from '@vvfx/ge-ir';
+
+const ir = convertGEToIR(scene, { frameRate: 30 });
+const roundTrippedScene = convertIRToGE(ir);
+```
+
+- `convertIRToGE(ir, duration?)`：IR -> GE JSONScene。
+- `convertGEToIR(scene, options)`：GE JSONScene -> IRComposition。
+- `GE2IROptions`：当前包含 `frameRate`。
+- `JSONScene` / `DataPath`：从 `@galacean/effects-specification` 透出，方便 sibling 包消费。
+
+## 共享契约
+
+`src/shared/coordinate.ts` 是正反向坐标换算的共同真源：
+
+- `DEFAULT_CAMERA_Z`
+- `DEFAULT_CAMERA_FOV`
+- `DEFAULT_CLIP_MODE`
+- `get2dTo3dRatio`
+- `convert2dTo3dPoint`
+
+`src/shared/ge2ir-metadata.ts` 是 round-trip passthrough metadata 的共同真源。`ge2ir`
+写入 `layer.metadata.ge2ir`，`ir2ge` 在生成 GE 时读取并复用原始 GE 动画和 mask 信息。
+
+当前支持的 metadata keys：
+
+- `positionOverLifetime`
+- `rotationOverLifetime`
+- `sizeOverLifetime`
+- `colorOverLifetime`
+- `geComponentId`
+- `geMask`
+
+`src/shared/types.ts` 放置不属于单一方向的 GE wire/pool 基础结构：
+
+- `GERecord`
+- `GEDataPath`
+- `GEPoolIndex`
+- `GETransform`
+- `GEItem`
+- `ECSCollector`
+
+## 稳定性分层
+
+`src/index.ts` 按三层导出：
+
+- 公开/主链路：`convertIRToGE`、`convertGEToIR`、基础类型。
+- sibling 包 API：`readLottieSpecific`、`isTransformOnlyParentLink`、部分 GE 处理中间类型。
+- debug internals：bezier/timeline/post-process/utils 等调试链路会用到的内部符号。

package/dist/ge2ir/converter.d.ts

@@ -0,0 +1,3 @@
+import type { IRComposition } from '@vvfx/animation-ir';
+import type { GE2IROptions } from './types';
+export declare function convertGEToIR(scene: Record<string, unknown>, options: GE2IROptions): IRComposition;

package/dist/ge2ir/index.d.ts

@@ -0,0 +1,2 @@
+export { convertGEToIR } from './converter';
+export type { GE2IROptions } from './types';

package/dist/ge2ir/merge/merge.d.ts

@@ -0,0 +1,9 @@
+import type { IRLayerNode } from '@vvfx/animation-ir';
+import type { GESceneContext } from '../types';
+export interface RawLayerDescriptor {
+    itemId: string;
+    item: Record<string, unknown>;
+    layer: IRLayerNode;
+}
+export declare function mergeNullSpritePairs(descriptors: RawLayerDescriptor[], ctx: GESceneContext): RawLayerDescriptor[];
+export declare function resolveHierarchy(descriptors: RawLayerDescriptor[], ctx: GESceneContext): void;

package/dist/ge2ir/parsers/animation-parser.d.ts

@@ -0,0 +1,4 @@
+import type { IRAnimatedProperty, IRTransformChannels } from '@vvfx/animation-ir';
+import type { GESceneContext } from '../types';
+export declare function parseTransformAnimation(asset: Record<string, unknown>, startFrame: number, endFrame: number, ctx: GESceneContext): Partial<IRTransformChannels>;
+export declare function parseOpacityAnimation(asset: Record<string, unknown>, startFrame: number, endFrame: number): IRAnimatedProperty<number> | undefined;

package/dist/ge2ir/parsers/component-parser.d.ts

@@ -0,0 +1,16 @@
+import type { IRAssetReference, IRBlendMode, IRColor, IRShapeData, IRTextData } from '@vvfx/animation-ir';
+import type { GESceneContext } from '../types';
+export interface ComponentData {
+    type: 'image' | 'solid' | 'text' | 'shape';
+    asset?: IRAssetReference;
+    solidColor?: IRColor;
+    text?: IRTextData;
+    shapes?: IRShapeData[];
+    blendMode?: IRBlendMode;
+    anchorScale?: [number, number];
+    /** Original GE component id — rendezvous key for cross-component references (masks). */
+    geComponentId?: string;
+    /** Raw GE component-level `mask` object (source: {isMask:true,...}, target: {isMask:false,reference,inverted}). */
+    rawMask?: Record<string, unknown>;
+}
+export declare function parseComponent(item: Record<string, unknown>, ctx: GESceneContext): ComponentData | undefined;

package/dist/ge2ir/parsers/keyframe-parser.d.ts

@@ -0,0 +1,7 @@
+import type { IRBezierHandle, IRKeyframe } from '@vvfx/animation-ir';
+export declare function parseBezierKeyframes(curves: unknown[], startFrame: number, endFrame: number): IRKeyframe<number>[];
+export declare function parsePositionTimingKeyframes(curves: unknown[], startFrame: number, endFrame: number): Array<{
+    t: number;
+    outTangent?: IRBezierHandle;
+    inTangent?: IRBezierHandle;
+}>;

package/dist/ge2ir/parsers/timeline-parser.d.ts

@@ -0,0 +1,9 @@
+import type { GESceneContext } from '../types';
+export interface TimelineData {
+    delay: number;
+    duration: number;
+    endBehavior: number;
+    transformAsset?: Record<string, unknown>;
+    spriteColorAsset?: Record<string, unknown>;
+}
+export declare function parseTimeline(itemId: string, ctx: GESceneContext): TimelineData | undefined;

package/dist/ge2ir/parsers/transform-parser.d.ts

@@ -0,0 +1,3 @@
+import type { IRTransformChannels } from '@vvfx/animation-ir';
+import type { GESceneContext } from '../types';
+export declare function parseStaticTransform(itemTransform: Record<string, unknown>, ctx: GESceneContext): Partial<IRTransformChannels>;

package/dist/ge2ir/pool/pool.d.ts

@@ -0,0 +1,4 @@
+import type { GEPoolIndex, GERecord } from '../../shared/types';
+export declare function buildPoolIndex(pool: GERecord[] | undefined): GEPoolIndex;
+export declare function resolveDataPath(pool: GEPoolIndex, ref: unknown): GERecord | undefined;
+export declare function resolveDataPathId(ref: unknown): string | undefined;

package/dist/ge2ir/reverse/blend-mode.d.ts

@@ -0,0 +1,2 @@
+import type { IRBlendMode as IRBlendModeType } from '@vvfx/animation-ir';
+export declare function reverseBlendMode(geCode: number | undefined): IRBlendModeType | undefined;

package/dist/ge2ir/reverse/coordinate.d.ts

@@ -0,0 +1 @@
+export declare function convert3dTo2dPoint(x: number, y: number, z: number, width: number, height: number): [number, number, number];

package/dist/ge2ir/reverse/end-behavior.d.ts

@@ -0,0 +1,3 @@
+import type { IREndBehavior as IREndBehaviorType } from '@vvfx/animation-ir';
+export declare function reverseEndBehavior(geBehavior: number | undefined): IREndBehaviorType | undefined;
+export declare function reverseCompositionEndBehavior(geBehavior: number | undefined): IREndBehaviorType | undefined;

package/dist/ge2ir/reverse/timing.d.ts

@@ -0,0 +1,2 @@
+import type { IRTimeContext } from '@vvfx/animation-ir';
+export declare function reverseLayerTiming(delay: number, duration: number, frameRate: number): IRTimeContext;

package/dist/ge2ir/scene-reader.d.ts

@@ -0,0 +1,3 @@
+import type { GE2IROptions, GESceneContext } from './types';
+export declare function buildSceneContext(scene: Record<string, unknown>, options: GE2IROptions): GESceneContext;
+export declare function getCompositionItemIds(scene: Record<string, unknown>): string[];

package/dist/ge2ir/types.d.ts

@@ -0,0 +1,24 @@
+import type { IRColor, IREndBehavior } from '@vvfx/animation-ir';
+import type { GEPoolIndex } from '../shared/types';
+export interface GE2IROptions {
+    frameRate: number;
+}
+export type { GE2IRPassthroughMetadata } from '../shared/ge2ir-metadata';
+export interface GESceneContext {
+    width: number;
+    height: number;
+    frameRate: number;
+    ratio: number;
+    duration: number;
+    inPoint: number;
+    outPoint: number;
+    compositionName: string;
+    endBehavior?: IREndBehavior;
+    backgroundColor?: IRColor;
+    itemById: GEPoolIndex;
+    componentById: GEPoolIndex;
+    miscById: GEPoolIndex;
+    imageById: GEPoolIndex;
+    textureById: GEPoolIndex;
+    itemIdToTrackId: Map<string, string>;
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export { convertIRToGE } from './ir2ge/assembly/generator';
+export { convertGEToIR } from './ge2ir/converter';
+export type { GE2IROptions } from './ge2ir/types';
+export type { DataPath, JSONScene } from '@galacean/effects-specification';
+export { readLottieSpecific } from './ir2ge/ir/specific';
+export type { LottieLayerSpecific } from './ir2ge/ir/specific';
+export { isTransformOnlyParentLink } from './ir2ge/ir/parent-link';
+export type { ECSCollector, GEDataPath, GEItem, GEPoolIndex, GERecord, GETransform } from './shared/types';
+export type { ProcessedItem, TransformAnimation } from './ir2ge/types';
+export { DEFAULT_CAMERA_Z, DEFAULT_CAMERA_FOV, DEFAULT_CLIP_MODE, get2dTo3dRatio, convert2dTo3dPoint, } from './shared/coordinate';
+export type { GE2IRPassthroughMetadata } from './shared/ge2ir-metadata';
+export { assembleScene } from './ir2ge/assembly/scene-assembly';
+export { estimateTextWidth, roundNumber, lerp, createId, toDataPath } from './ir2ge/utils';
+export { irScalarKeyframesToGE, irVectorKeyframesToGE, irPositionKeyframesToGE, shouldUseKeyframeMode, } from './ir2ge/builders/bezier';
+export type { IRToGETimeContext, IRPositionGEResult } from './ir2ge/builders/bezier';
+export { buildTimelineTracks } from './ir2ge/builders/timeline';
+export { normalizeChildVisibilityByParentDelays } from './ir2ge/post-process/visibility';