@vvfx/sdk 0.2.8 → 0.2.10

package/dist/utils/background-manager.js

@@ -0,0 +1,189 @@
+/**
+ * @description 背景管理器
+ * 负责管理画布背景的配置、渲染和跟随变换
+ */
+export class BackgroundManager {
+    /**
+     * @description 默认网格配置
+     */
+    static DEFAULT_GRID_CONFIG = {
+        baseSize: 16,
+        zoomCycle: 2,
+        minSize: 8,
+    };
+    /**
+     * @description 背景预设配置
+     */
+    static PRESETS = {
+        'dot-board': {
+            color: '#F5F5F5',
+            image: 'radial-gradient(circle 1px at 8px 8px, #BBBBBB 50%, transparent 100%)',
+            repeat: 'repeat',
+            position: '0 0',
+            size: '16px 16px',
+        },
+        'chess-board': {
+            color: '#CCCCCC',
+            image: 'linear-gradient(45deg, #FFFFFF 25%, transparent 25%, transparent 75%, #FFFFFF 75%),linear-gradient(45deg, #FFFFFF 25%, transparent 25%, transparent 75%, #FFFFFF 75%)',
+            repeat: 'repeat',
+            position: '0 0, 8px 8px',
+            size: '16px 16px',
+        },
+    };
+    container = null;
+    config;
+    /**
+     * @description 当前背景位置（用于跟随移动）
+     */
+    offsetX = 0;
+    offsetY = 0;
+    constructor(config) {
+        this.config = { ...BackgroundManager.DEFAULT_GRID_CONFIG, ...config };
+    }
+    /**
+     * @description 绑定容器元素
+     * @param element 画布容器元素
+     */
+    attach(element) {
+        this.container = element;
+    }
+    /**
+     * @description 解绑容器元素
+     */
+    detach() {
+        this.container = null;
+    }
+    /**
+     * @description 应用背景预设
+     * @param presetName 预设名称
+     * @param color 可选的背景色覆盖
+     */
+    applyPreset(presetName, color) {
+        if (!this.container) {
+            return false;
+        }
+        const preset = BackgroundManager.PRESETS[presetName];
+        if (!preset) {
+            console.warn(`Unknown background preset: ${presetName}`);
+            return false;
+        }
+        const element = this.container.parentElement;
+        if (!element) {
+            return false;
+        }
+        // 清除旧样式
+        this.clearBackground(element);
+        // 应用新样式
+        if (preset.color || color) {
+            element.style.backgroundColor = color ?? preset.color ?? '';
+        }
+        if (preset.image) {
+            element.style.backgroundImage = preset.image;
+        }
+        if (preset.repeat) {
+            element.style.backgroundRepeat = preset.repeat;
+        }
+        if (preset.position) {
+            element.style.backgroundPosition = preset.position;
+            // 初始化内部位置追踪
+            this.offsetX = 0;
+            this.offsetY = 0;
+        }
+        if (preset.size) {
+            element.style.backgroundSize = preset.size;
+        }
+        return true;
+    }
+    /**
+     * @description 设置纯色背景
+     * @param color 颜色值
+     */
+    setColorBackground(color) {
+        if (!this.container) {
+            return;
+        }
+        const element = this.container.parentElement;
+        if (!element) {
+            return;
+        }
+        this.clearBackground(element);
+        element.style.backgroundColor = color;
+    }
+    /**
+     * @description 设置图片背景
+     * @param url 图片 URL
+     */
+    setImageBackground(url) {
+        if (!this.container) {
+            return;
+        }
+        const element = this.container.parentElement;
+        if (!element) {
+            return;
+        }
+        this.clearBackground(element);
+        element.style.backgroundImage = `url(${url})`;
+    }
+    /**
+     * @description 更新背景变换（跟随画布移动和缩放）
+     * @param shift 画布移动的偏移量
+     * @param zoom 当前缩放比例
+     */
+    updateTransform(shift, zoom) {
+        if (!this.container) {
+            return;
+        }
+        const parentElement = this.container.parentElement;
+        if (!parentElement) {
+            return;
+        }
+        // 更新位置偏移
+        this.offsetX += shift.x;
+        this.offsetY += shift.y;
+        // 计算循环缩放比例
+        const bgZoom = this.calculateZoomCycle(zoom);
+        // 根据循环缩放比例计算新的网格大小
+        const newSize = Math.max(this.config.minSize, this.config.baseSize * bgZoom);
+        // 更新背景样式
+        parentElement.style.backgroundPosition = `${this.offsetX}px ${this.offsetY}px , ${this.offsetX + newSize / 2}px ${this.offsetY + newSize / 2}px`;
+        parentElement.style.backgroundSize = `${newSize}px ${newSize}px`;
+    }
+    /**
+     * @description 重置背景位置和大小
+     */
+    reset() {
+        this.offsetX = 0;
+        this.offsetY = 0;
+        if (!this.container) {
+            return;
+        }
+        const parentElement = this.container.parentElement;
+        if (!parentElement) {
+            return;
+        }
+        parentElement.style.backgroundPosition = '';
+        parentElement.style.backgroundSize = '';
+    }
+    /**
+     * @description 清除背景样式
+     */
+    clearBackground(element) {
+        element.style.removeProperty('background-color');
+        element.style.removeProperty('background-image');
+        element.style.removeProperty('background-repeat');
+        element.style.removeProperty('background-position');
+        element.style.removeProperty('background-size');
+    }
+    /**
+     * @description 计算循环缩放比例
+     * zoom 在 [1, 2) 时，bgZoom = zoom
+     * zoom 在 [2, 4) 时，bgZoom = zoom / 2
+     * zoom 在 [0.5, 1) 时，bgZoom = zoom / 0.5
+     */
+    calculateZoomCycle(zoom) {
+        const { zoomCycle } = this.config;
+        const logZoom = Math.log(zoom) / Math.log(zoomCycle);
+        const power = Math.floor(logZoom);
+        return zoom / Math.pow(zoomCycle, power);
+    }
+}

package/dist/utils/common-utils.js

@@ -0,0 +1,183 @@
+import { DEG2RAD, Matrix4, Quaternion, roundNumber, Vector3 } from '../math';
+export function arrAdd(arr, item) {
+    if (!arr.includes(item)) {
+        arr.push(item);
+    }
+}
+export function isObj(item) {
+    return typeof item === 'object' && !!item;
+}
+export function deepEquals(a, b) {
+    if (isObj(a) && isObj(b)) {
+        if (Array.isArray(a) && Array.isArray(b)) {
+            if (a.length === b.length) {
+                return a.every((item, index) => deepEquals(item, b[index]));
+            }
+            return false;
+        }
+        const kas = [];
+        for (const key in a) {
+            if (Object.prototype.hasOwnProperty.call(a, key)) {
+                if (!deepEquals(a[key], b[key])) {
+                    return false;
+                }
+                kas.push(key);
+            }
+        }
+        return Object.getOwnPropertyNames(b).length === kas.length;
+    }
+    return a === b;
+}
+// lodash.clonedeep 太大了，直接使用简单版
+export function deepClone(target) {
+    if (target === undefined) {
+        return undefined;
+    }
+    return JSON.parse(JSON.stringify(target));
+}
+export function getColorByNormalizeColor(color) {
+    return color.map((c, index) => index < 3 ? roundNumber(c * 255, 0) : c);
+}
+export function getNormalizeColorByColor(color) {
+    return color.map((c, index) => index < 3 ? roundNumber(c / 255, 4) : c);
+}
+export function getTransformRatioByViewAndCamera(viewSize, cameraPosition, cameraFov, cameraNear, cameraFar, isReverse) {
+    const viewMatrix = new Matrix4().compose(cameraPosition, new Quaternion(), new Vector3(1, 1, 1)).invert();
+    const projectMatrix = new Matrix4().perspective(cameraFov * DEG2RAD, viewSize.x / viewSize.y, cameraNear, cameraFar, isReverse);
+    const vpMatrix = new Matrix4().multiplyMatrices(projectMatrix, viewMatrix);
+    const inverseVPMatrix = vpMatrix.clone().invert();
+    const z = vpMatrix.projectPoint(new Vector3()).z;
+    const start = new Vector3(0, 0, z).applyMatrix(inverseVPMatrix);
+    const end = new Vector3(2, 2, z).applyMatrix(inverseVPMatrix);
+    const xRatio = Math.abs(end.x - start.x) / viewSize.x;
+    const yRatio = Math.abs(end.y - start.y) / viewSize.y;
+    return { xRatio, yRatio };
+}
+export function assertExist(item, msg = 'item doesn\'t exist') {
+    if (item === undefined || item === null) {
+        throw new Error(msg);
+    }
+}
+export function asserts(condition, msg = 'asserts failed') {
+    if (!condition) {
+        throw new Error(msg);
+    }
+}
+export function logger(level, prefixs, ...args) {
+    const flag = prefixs.reduce((acc, curr) => acc ? `${acc} ${curr}` : curr, '');
+    const style = 'color: #108ee9;';
+    switch (level) {
+        case 'error':
+            console.error(`%c[${flag}]`, style, ...args);
+            break;
+        case 'info':
+            console.info(`%c[${flag}]`, style, ...args);
+            break;
+        case 'debug':
+            console.debug(`%c[${flag}]`, style, ...args);
+            break;
+        case 'warn':
+            console.warn(`%c[${flag}]`, style, ...args);
+            break;
+        case 'log':
+            console.log(`%c[${flag}]`, style, ...args);
+            break;
+        default:
+            console.log(`%c[${flag}]`, style, ...args);
+            break;
+    }
+}
+export function loadScriptAsync(src, attrs = {}) {
+    return new Promise((resolve, reject) => {
+        // 检查是否已加载过该脚本，避免重复加载
+        const existingScript = document.querySelector(`script[src="${src}"]`);
+        if (existingScript) {
+            if (existingScript.dataset.loaded === 'true') {
+                resolve(existingScript);
+                return;
+            }
+            existingScript.addEventListener('load', () => {
+                resolve(existingScript);
+            });
+            existingScript.addEventListener('error', () => {
+                reject(new Error(`Script already failed: ${src}`));
+            });
+            return;
+        }
+        // 不存在，则创建新的 script 元素
+        const scriptEl = document.createElement('script');
+        scriptEl.src = src;
+        scriptEl.async = true;
+        Object.keys(attrs).forEach(attrKey => {
+            scriptEl.setAttribute(attrKey, attrs[attrKey] ?? '');
+        });
+        scriptEl.onload = () => {
+            scriptEl.dataset.loaded = 'true';
+            resolve(scriptEl);
+        };
+        scriptEl.onerror = () => {
+            reject(new Error(`Failed to load script: ${src}`));
+        };
+        document.head.appendChild(scriptEl);
+    });
+}
+export function downloadBlob(buffer, filename, mimeType = 'application/octet-stream') {
+    const blob = new Blob(Array.isArray(buffer) ? buffer : [buffer], { type: mimeType });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+}
+export function getUniqueName(name, names) {
+    if (!names.includes(name)) {
+        return name;
+    }
+    let i = 1;
+    let newName = `${name} (${i})`;
+    while (names.includes(newName)) {
+        i++;
+        newName = `${name} (${i})`;
+    }
+    return newName;
+}
+/**
+ * 深度比较两个值是否相等
+ */
+export function isEqual(a, b) {
+    if (Object.is(a, b)) {
+        return true;
+    }
+    if (typeof a !== typeof b) {
+        return false;
+    }
+    if (a === null || typeof a !== 'object') {
+        return false;
+    }
+    if (a instanceof Date && b instanceof Date) {
+        return a.getTime() === b.getTime();
+    }
+    if (a instanceof RegExp && b instanceof RegExp) {
+        return a.toString() === b.toString();
+    }
+    if (Array.isArray(a) !== Array.isArray(b)) {
+        return false;
+    }
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) {
+        return false;
+    }
+    for (const key of keysA) {
+        if (!Object.prototype.hasOwnProperty.call(b, key)) {
+            return false;
+        }
+        if (!isEqual(a[key], b[key])) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/utils/index.js

@@ -0,0 +1,8 @@
+export * from './common-utils';
+export * from './background-manager';
+export * from './interaction-utils';
+export * from './json-data-utils';
+export * from './layout-utils';
+export * from './types';
+export * from './player-data-utils';
+export * from './page-data-utils';

package/dist/utils/interaction-utils.js

@@ -0,0 +1,205 @@
+import { assertExist } from '@galacean/effects';
+import { Ray, Euler, Plane, Vector2, Vector3, Matrix4, RayCaster, Quaternion, } from '../math';
+import { SDK } from '../sdk';
+export class InteractionUtils {
+    /**
+     * @description 交互平面
+     */
+    plane = new Plane();
+    /**
+     * @description 交互射线
+     */
+    ray = new Ray();
+    /**
+     * @description 交互状态视图信息
+     */
+    viewportParam = {
+        width: 0,
+        height: 0,
+        scale: 1,
+        translation: new Vector2(),
+        rulerWidth: 0,
+    };
+    /**
+     * @description 交互状态相机信息
+     */
+    cameraParam = {
+        position: new Vector3(),
+        rotation: new Vector3(),
+        focusPosition: new Vector3(),
+        focusRotation: new Vector3(),
+        viewProjectionMatrix: new Matrix4(),
+        inverseViewProjectionMatrix: new Matrix4(),
+    };
+    pageDataUtils;
+    constructor(utils) {
+        this.pageDataUtils = utils;
+    }
+    refreshViewParam() {
+        const pageData = this.pageDataUtils.getPageData();
+        assertExist(pageData, 'You must run SDK first');
+        const viewSize = new Vector2(this.pageDataUtils.container.offsetWidth, this.pageDataUtils.container.offsetHeight);
+        const { zoom, translation } = pageData.property;
+        this.viewportParam.width = viewSize.x;
+        this.viewportParam.height = viewSize.y;
+        this.viewportParam.scale = zoom;
+        this.viewportParam.translation = new Vector2(...translation);
+        this.viewportParam.rulerWidth = 0;
+    }
+    refreshCameraParam() {
+        const { player } = this.pageDataUtils;
+        const playerCamera = player?.getCompositions()?.[0]?.camera;
+        if (playerCamera) {
+            const vpMatrix = Matrix4.fromArray(playerCamera.getViewProjectionMatrix().toArray());
+            // const viewportMatrix = new Matrix4().compose(viewTranslation, new Quaternion(), new Vector3(scale, scale, 1))
+            const viewMatrix = Matrix4.fromArray(playerCamera.getViewMatrix().toArray()).invert();
+            const quaternion = new Quaternion();
+            viewMatrix.decompose(this.cameraParam.position, quaternion, new Vector3());
+            this.cameraParam.rotation = new Euler().setFromQuaternion(quaternion).toDegreeVector3();
+            // 相机始终朝向 [0, 0, -1],所以当相机位置小于0时，以其与原点的z轴距离作为交互平面中心位置
+            this.cameraParam.focusPosition = new Vector3(...this.cameraParam.position.toVector2().toArray(), this.cameraParam.position.z > 0 ? 0 : this.cameraParam.position.z * 2);
+            this.cameraParam.focusPosition.applyEuler(new Euler().setFromDegreeVector3(this.cameraParam.rotation.clone()), this.cameraParam.position);
+            this.cameraParam.focusRotation = new Euler().setFromQuaternion(quaternion.invert()).toDegreeVector3();
+            this.cameraParam.viewProjectionMatrix = vpMatrix;
+            this.cameraParam.inverseViewProjectionMatrix = Matrix4.fromArray(playerCamera.getInverseViewProjectionMatrix().toArray());
+        }
+    }
+    refrehCameraParamByCameraInfo(camera) {
+        const { near, far, fov, aspect, position, clipMode } = camera;
+        const projectMatrix = new Matrix4().perspective(fov * Math.PI / 180, aspect, near, far, clipMode === 1);
+        const viewMatrix = new Matrix4().compose(new Vector3(...position), new Quaternion(), new Vector3(1, 1, 1)).invert();
+        const vpMatrix = new Matrix4().multiplyMatrices(projectMatrix, viewMatrix);
+        const inverseVpMatrix = vpMatrix.clone().invert();
+        this.cameraParam.position = new Vector3(...position);
+        this.cameraParam.rotation = new Euler().toDegreeVector3();
+        this.cameraParam.focusPosition = new Vector3(position[0], position[1], this.cameraParam.position.z > 0 ? 0 : this.cameraParam.position.z * 2);
+        this.cameraParam.focusPosition.applyEuler(new Euler().setFromDegreeVector3(this.cameraParam.rotation.clone()), this.cameraParam.position);
+        this.cameraParam.focusRotation = new Euler().toDegreeVector3();
+        this.cameraParam.viewProjectionMatrix = vpMatrix;
+        this.cameraParam.inverseViewProjectionMatrix = inverseVpMatrix;
+    }
+    initInteractionPlane(position, rotation) {
+        position ??= this.cameraParam.focusPosition;
+        rotation ??= new Euler().setFromDegreeVector3(this.cameraParam.rotation);
+        const normal = new Vector3(0, 0, 1).applyEuler(rotation);
+        this.plane.setFromNormalAndCoplanarPoint(position, normal);
+    }
+    /**
+     * @description 根据视图空间大小获取空间大小
+     * @param viewSize 视图空间大小
+     * @param isWorld 是否依赖于世界坐标系 - 世界坐标系下，以当前相机锁定平面为基准进行运算；本地坐标系下，以元素坐标系进行运算[用于决定交互平面]
+     * @param targetItem 目标元素
+     */
+    getWorldSizeByViewSize(viewSize, isWorld = true, itemId) {
+        // 交互平面需要旋转与相机相同角度
+        const rotation = isWorld || !itemId
+            ? new Euler().setFromDegreeVector3(this.cameraParam.rotation)
+            : new Euler().setFromQuaternion(new Quaternion().setFromRotationMatrix(this.pageDataUtils.getItemTransformById(itemId).matrix));
+        const position = itemId
+            ? new Vector3().setFromMatrixPosition(this.pageDataUtils.getItemTransformById(itemId).matrix)
+            : this.cameraParam.focusPosition;
+        const viewportScale = SDK.config.mode === 'editor' ? 1 : this.viewportParam.scale;
+        viewSize.multiply(viewportScale);
+        const focusViewPoint = this.projectPoint(position.clone());
+        const nextPoint = this.getWorldPositionByViewPoint(focusViewPoint.add(viewSize));
+        if (!nextPoint) {
+            console.warn('size is out of bounds.');
+            return new Vector3(0, 0, 0);
+        }
+        const resultRotation = new Euler().setFromQuaternion(new Quaternion().setFromEuler(rotation).invert());
+        const resultPosition = isWorld || !itemId ? nextPoint.applyEuler(resultRotation, position) : nextPoint;
+        const worldSize = resultPosition.subtract(position);
+        return worldSize;
+    }
+    /**
+     * @description 获取 template 模式下视图与场景的缩放比 (viewportWidth / sceneWidth)
+     *              场景未就绪时回退到 1，并打印一次 warning
+     */
+    getTemplateViewScale() {
+        const sceneSize = this.pageDataUtils.getSceneSize();
+        if (!sceneSize) {
+            console.warn('Scene is not existed, view scale will fallback to 1.');
+            return 1;
+        }
+        return this.viewportParam.width / sceneSize.x;
+    }
+    getViewSizeByPixelSize(pixelSize) {
+        const { scale } = this.viewportParam;
+        const resultScale = SDK.config.mode === 'template' ? this.getTemplateViewScale() : scale;
+        return pixelSize.clone().multiply(resultScale);
+    }
+    /**
+     * @description 对空间坐标进行投影
+     * @param point 空间坐标
+     * @param isGestureHandlerView 是否投影到辅助视图下 - 辅助试图与实际视图大小可能会有区别
+     */
+    projectPoint(point) {
+        const { width, height, scale } = this.viewportParam;
+        const { viewProjectionMatrix } = this.cameraParam;
+        const viewportScale = SDK.config.mode === 'editor' ? 1 : scale;
+        const viewPoint = new Vector2().copyFrom(point.applyMatrix(viewProjectionMatrix).toVector2()).toViewCoordinate(width * viewportScale, height * viewportScale);
+        return viewPoint;
+    }
+    /**
+     * @description 通过屏幕坐标获取世界坐标
+     * @param point 屏幕坐标
+     * @returns 世界坐标
+     */
+    getWorldPositionByViewPoint(point) {
+        const { position, inverseViewProjectionMatrix: inverseViewProjectMatrix } = this.cameraParam;
+        // 刷新射线碰撞器
+        const coords = this.getNDCPositionByScreenPosition(point);
+        const rayCaster = new RayCaster().setFromCamera(coords, { position, inverseViewProjectMatrix });
+        // 计算射线碰撞结果
+        const result = rayCaster.rayCastPlane(this.plane);
+        return result?.point;
+    }
+    getNDCPositionByScreenPosition(point) {
+        const { width, height, scale } = this.viewportParam;
+        const resultScale = SDK.config.mode === 'editor' ? 1 : scale;
+        return new Vector2(point.x / (width * resultScale) * 2 - 1, 1 - point.y / (height * resultScale) * 2);
+    }
+    getNDCSizeByPixelSize(pixelSize) {
+        const { width, height } = this.viewportParam;
+        return new Vector2((pixelSize.x / width) * 2, -(pixelSize.y / height) * 2);
+    }
+    getViewPositionWWithOutTransform(point) {
+        const { scale } = this.viewportParam;
+        const resultScale = SDK.config.mode === 'editor' ? 1 : scale;
+        return point.divide(resultScale);
+    }
+    getViewPositionByPixelPoint(point) {
+        const { width, height, scale, translation } = this.viewportParam;
+        if (SDK.config.mode === 'template') {
+            const viewScale = this.getTemplateViewScale();
+            // 注意：必须 clone，避免修改入参
+            return point.clone().multiply(viewScale * scale);
+        }
+        return point.clone().scaleByCenter(new Vector2(scale, scale), new Vector2(width / 2, height / 2)).add(translation);
+    }
+    getPixelPositionByViewPoint(point) {
+        const { width, height, scale, translation } = this.viewportParam;
+        if (SDK.config.mode === 'template') {
+            const viewScale = this.getTemplateViewScale();
+            // 注意：必须 clone，避免修改入参
+            return point.clone().divide(viewScale * scale);
+        }
+        return point.clone().subtract(translation.clone()).scaleByCenter(new Vector2(1 / scale, 1 / scale), new Vector2(width / 2, height / 2));
+    }
+    getPixelSizeByWorldSize(worldSize) {
+        const startPoint = this.projectPoint(new Vector3());
+        const targetPoint = this.projectPoint(worldSize);
+        const pixelSize = targetPoint.subtract(startPoint);
+        pixelSize.abs();
+        return pixelSize;
+    }
+    getPixelSizeByNDCSize(ndcSize) {
+        const { width, height } = this.viewportParam;
+        return new Vector2(ndcSize.x / 2 * width, -ndcSize.y / 2 * height);
+    }
+    getPixelSizeByViewSize(viewSize) {
+        const { scale } = this.viewportParam;
+        const resultScale = SDK.config.mode === 'template' ? this.getTemplateViewScale() * scale : scale;
+        return viewSize.clone().divide(resultScale);
+    }
+}