@xtctwins/tctwins-core 1.1.5 → 1.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xtctwins/tctwins-core",
-	"version": "1.1.5",
+	"version": "1.1.7",
 	"private": false,
 	"description": "Web Programming Toolkit for 3D/2D BIM and CAD",
 	"module": "./dist/tctwins-core.es5.js",
@@ -11,7 +11,7 @@
 		"dev": "webpack --config webpack.min.config.js",
 		"publish": "npm publish --access public",
 		"release": "npm version patch && npm publish --access public",
-		"vite-dev": "vite --open --mode dev"
+		"serve": "vite --open --mode dev"
 	},
 	"keywords": [
 		"webgl",
@@ -75,4 +75,4 @@
 		"/dist",
 		"/types"
 	]
-}
+}

package/types/plugins/ObjectEditPlugin/ObjectEditPlugin.d.ts

@@ -0,0 +1,242 @@
+import { Plugin, Viewer } from "../../viewer";
+
+export declare type ObjectEditPluginConfiguration = {
+	/** 可选 ID，用于通过 {@link Viewer.plugins} 查找此插件。 */
+	id?: string;
+};
+
+/**
+ * ObjectEditPlugin 是 {@link Viewer} 插件，提供交互式 3D 变换控件（平移 / 旋转 / 缩放），
+ * 以及构件的染色、透视、隐藏等快捷操作。
+ *
+ * 同时支持 Instance 层和 Batch（VBO）层构件。Batch 构件的旋转通过 GPU 逐顶点矩阵实现。
+ *
+ * ## 快速开始
+ * ```js
+ * const edit = new ObjectEditPlugin(viewer);
+ *
+ * // 1. 选中构件
+ * edit.setTargets(["entityId1", "entityId2"]);
+ *
+ * // 2. 显示 Gizmo（平移箭头 + 旋转圆环 + 缩放方块）
+ * edit.showControl();
+ *
+ * // 3. 拖拽 Gizmo 手柄进行交互式编辑
+ *
+ * // 4. 或通过代码控制：
+ * edit.translate([1, 0, 0]);             // 沿 X 平移 1 单位
+ * edit.rotate([0, 1, 0], 45);           // 绕 Y 轴旋转 45°
+ * edit.setRotation([0, 0.707, 0, 0.707]); // 设置绝对旋转（四元数）
+ * edit.animateRotation([0, 1, 0], 90);  // 绕 Y 轴持续旋转 90°/s
+ * edit.setScale([1.5, 1.5, 1.5]);       // 缩放 1.5 倍
+ * edit.resetTransform();                // 重置所有变换
+ *
+ * // 5. 样式编辑
+ * edit.colorize([1, 0.2, 0.2]);         // 染红
+ * edit.setXRayed(true);                 // 透视模式
+ * edit.setHidden(true);                 // 隐藏
+ *
+ * // 6. 隐藏 Gizmo
+ * edit.hideControl();
+ * ```
+ *
+ * ## 事件
+ * ```js
+ * edit.on("editStart",      () => {});
+ * edit.on("editEnd",        () => {});
+ * edit.on("translated",     (delta: number[]) => {});
+ * edit.on("rotated",        ({ axis, degrees }: { axis: number[]; degrees: number }) => {});
+ * edit.on("rotationSet",    (quat: number[]) => {});
+ * edit.on("scaleSet",       (scale: number[]) => {});
+ * edit.on("transformReset", () => {});
+ * edit.on("animStart",      ({ axis, degreesPerSec, duration }: { axis: number[]; degreesPerSec: number; duration?: number }) => {});
+ * edit.on("animStop",       () => {});
+ * edit.on("controlVisible", (visible: boolean) => {});
+ * edit.on("colorized",      (rgb: number[]) => {});
+ * edit.on("xrayed",         (on: boolean) => {});
+ * edit.on("hidden",         (on: boolean) => {});
+ * ```
+ *
+ * ## Gizmo 手柄
+ *
+ * | 手柄       | 颜色   | 操作     |
+ * |------------|--------|----------|
+ * | 箭头杆     | R/G/B  | 平移     |
+ * | 弯曲圆环   | R/G/B  | 旋转     |
+ * | 方形盒子   | R/G/B  | 单轴缩放 |
+ * | 中央黄盒   | 黄     | 均匀缩放 |
+ */
+export declare class ObjectEditPlugin extends Plugin {
+	/**
+	 * @constructor
+	 * @param viewer Viewer 实例。
+	 * @param cfg 插件配置。
+	 */
+	constructor(viewer: Viewer, cfg?: ObjectEditPluginConfiguration);
+
+	// ═══ 目标管理 ═══
+
+	/**
+	 * 设置要变换的目标构件 ID 列表。
+	 *
+	 * Gizmo 将定位在这些构件 AABB 的质心处。
+	 * 调用此方法会重置累计旋转状态。
+	 *
+	 * @param ids {@link Entity.id} 数组。
+	 */
+	setTargets(ids: string[]): void;
+
+	/**
+	 * 获取当前目标构件 ID 列表。
+	 *
+	 * @returns {@link Entity.id} 数组。
+	 */
+	getTargets(): string[];
+
+	// ═══ Gizmo 显示控制 ═══
+
+	/**
+	 * 显示变换 Gizmo。
+	 */
+	showControl(): void;
+
+	/**
+	 * 隐藏变换 Gizmo。
+	 */
+	hideControl(): void;
+
+	/**
+	 * Gizmo 是否可见。
+	 *
+	 * @returns 是否可见。
+	 */
+	isControlVisible(): boolean;
+
+	/**
+	 * 设置 Gizmo 的世界坐标位置（手动）。
+	 *
+	 * @param pos 3D 位置 [x, y, z]。
+	 */
+	setPosition(pos: number[]): void;
+
+	/**
+	 * 设置 Gizmo 的剔除状态（用于快照等场景）。
+	 *
+	 * @param culled 是否剔除。
+	 */
+	setCulled(culled: boolean): void;
+
+	// ═══ 变换操作（Batch + Instance 构件均支持） ═══
+
+	/**
+	 * 按世界空间增量平移目标构件。
+	 *
+	 * @param delta 平移增量 [dx, dy, dz]。
+	 */
+	translate(delta: number[]): void;
+
+	/**
+	 * 绕指定轴增量旋转目标构件。
+	 *
+	 * @param axis 归一化旋转轴 [x, y, z]。
+	 * @param degrees 旋转角度（度）。
+	 */
+	rotate(axis: number[], degrees: number): void;
+
+	/**
+	 * 设置目标构件的绝对旋转（四元数）。
+	 *
+	 * 对 Batch 和 Instance 构件均生效。Batch 构件绕自身中心旋转。
+	 *
+	 * @param quat 四元数 [x, y, z, w]。
+	 */
+	setRotation(quat: number[]): void;
+
+	/**
+	 * 设置目标构件的缩放（仅 Instance 层构件）。
+	 *
+	 * @param scale 缩放因子 [sx, sy, sz]。
+	 */
+	setScale(scale: number[]): void;
+
+	/**
+	 * 重置目标构件的所有变换（旋转 + 缩放归零/归一）。
+	 */
+	resetTransform(): void;
+
+	// ═══ 动画旋转 ═══
+
+	/**
+	 * 启动绕指定轴的持续旋转动画。
+	 *
+	 * 使用 requestAnimationFrame 驱动，带 delta-time 修正。
+	 * 再次调用会停止当前动画并启动新的。
+	 *
+	 * @param axis 归一化旋转轴 [x, y, z]。
+	 * @param degreesPerSec 旋转速度（度/秒）。
+	 * @param duration 可选，最大持续秒数。省略则持续旋转直到手动停止。
+	 *
+	 * @example
+	 * edit.animateRotation([0, 1, 0], 90);       // 绕 Y 轴 90°/s 持续旋转
+	 * edit.animateRotation([0, 0, 1], 180, 3);   // 绕 Z 轴 180°/s 旋转 3 秒后自动停止
+	 */
+	animateRotation(axis: number[], degreesPerSec: number, duration?: number): void;
+
+	/**
+	 * 停止旋转动画。
+	 */
+	stopAnimation(): void;
+
+	/**
+	 * 动画是否正在运行。
+	 *
+	 * @returns 是否正在动画。
+	 */
+	isAnimating(): boolean;
+
+	// ═══ 状态查询 ═══
+
+	/**
+	 * 获取当前世界空间质心位置。
+	 *
+	 * @returns 位置 [x, y, z]。
+	 */
+	getPosition(): number[];
+
+	/**
+	 * 获取当前累计旋转四元数。
+	 *
+	 * @returns 四元数 [x, y, z, w]，无旋转时返回 null。
+	 */
+	getRotation(): number[] | null;
+
+	// ═══ 样式快捷操作 ═══
+
+	/**
+	 * 染色选中构件。
+	 *
+	 * @param rgb RGB 颜色，各分量范围 0..1。
+	 */
+	colorize(rgb: number[]): void;
+
+	/**
+	 * 切换选中构件的透视模式。
+	 *
+	 * @param on 是否开启透视。
+	 */
+	setXRayed(on: boolean): void;
+
+	/**
+	 * 切换选中构件的可见性。
+	 *
+	 * @param on true=隐藏，false=显示。
+	 */
+	setHidden(on: boolean): void;
+
+	// ═══ 生命周期 ═══
+
+	/**
+	 * 销毁此插件。停止动画、解绑事件、销毁 Gizmo。
+	 */
+	destroy(): void;
+}

package/types/plugins/ObjectEditPlugin/index.d.ts

@@ -0,0 +1 @@
+export * from "./ObjectEditPlugin";

package/types/plugins/index.d.ts

@@ -12,6 +12,7 @@ export * from "./TreeViewPlugin";
 export * from "./ViewCullPlugin";
 export * from "./XTCLoaderPlugin";
 export * from "./WebIFCLoaderPlugin";
+export * from "./ObjectEditPlugin";
 export * from "./LASLoaderPlugin";
 
 export declare type ModelStats = {

package/types/viewer/Viewer.d.ts

@@ -267,4 +267,14 @@ export declare class Viewer {
 	/** Destroys this Viewer.
 	 */
 	destroy(callback?: Function): void;
+
+	/**
+	 * Focus camera on a given model (by ID or instance).
+	 * @param {String|Number|Object} modelId Model id or SceneModel instance
+	 * @param {*} [options] Options: { hideOthers: boolean, duration: number, callback: Function }
+	 */
+	focusModel(
+		modelId: string | number | any,
+		options?: { hideOthers?: boolean; duration?: number; callback?: Function }
+	): void;
 }

package/types/viewer/scene/scene/Scene.d.ts

@@ -249,7 +249,7 @@ export declare class Scene extends Component {
 	 */
 	get highlightedObjects(): { [key: string]: Entity };
 
-	get edgesObjects(): { [key: string]: Entity }
+	get edgesObjects(): { [key: string]: Entity };
 
 	/**
 	 * Map of currently selected {@link Entity}s that represent objects.
@@ -862,7 +862,7 @@ export declare class Scene extends Component {
 	 * @param {Number[]} [colorize=(1,1,1)] RGB colorize factors, multiplied by the rendered pixel colors.
 	 * @returns {Boolean} True if any {@link Entity}s changed opacity, else false if all updates were redundant and not applied.
 	 */
-	setObjectsColorized(ids: string[], colorize: number[]|null): boolean;
+	setObjectsColorized(ids: string[], colorize: number[] | null): boolean;
 
 	/**
 	 * Batch-updates {@link Entity.opacity} on {@link Entity}s that represent objects.
@@ -896,6 +896,160 @@ export declare class Scene extends Component {
 	 */
 	setObjectsOffset(ids: string[], offset: number[]): void;
 
+	/**
+	 * Batch-updates local translation on {@link Entity}s that represent objects.
+	 *
+	 * An {@link Entity} represents an object when {@link Entity.isObject} is ````true````.
+	 *
+	 * Only works on Entity types that have a ````position```` property
+	 * (e.g. {@link Mesh}, {@link SceneModelTransform}).
+	 *
+	 * @param {String[]} ids Array of {@link Entity.id} values.
+	 * @param {Number[]} position 3D position vector ````[x, y, z]````.
+	 * @returns {Boolean} True if any {@link Entity}s were updated, else false.
+	 */
+	setObjectsPosition(ids: string | string[], position: number[]): boolean;
+
+	/**
+	 * Gets the local translation of an object {@link Entity}.
+	 *
+	 * @param {String} id The {@link Entity.id}.
+	 * @returns {Number[]|null} 3D position vector ````[x, y, z]````, or ````null````.
+	 */
+	getObjectPosition(id: string): number[] | null;
+
+	/**
+	 * Batch-updates local translation on {@link Entity}s, with per-object values.
+	 *
+	 * @param positionMap Map from {@link Entity.id} to 3D position vector ````[x, y, z]````.
+	 * @returns {Boolean} True if any {@link Entity}s were updated, else false.
+	 */
+	setObjectsPositionMap(positionMap: { [id: string]: number[] }): boolean;
+
+	/**
+	 * Batch-updates local rotation on {@link Entity}s that represent objects.
+	 *
+	 * Only works on Entity types that have a ````rotation```` property.
+	 *
+	 * @param {String[]} ids Array of {@link Entity.id} values.
+	 * @param {Number[]} rotation Euler angles in degrees ````[rx, ry, rz]````.
+	 * @returns {Boolean} True if any {@link Entity}s were updated, else false.
+	 */
+	setObjectsRotation(ids: string | string[], rotation: number[]): boolean;
+
+	/**
+	 * Gets the local rotation of an object {@link Entity}.
+	 *
+	 * @param {String} id The {@link Entity.id}.
+	 * @returns {Number[]|null} Euler angles in degrees ````[rx, ry, rz]````, or ````null````.
+	 */
+	getObjectRotation(id: string): number[] | null;
+
+	/**
+	 * Batch-updates local rotation on {@link Entity}s, with per-object values.
+	 *
+	 * @param rotationMap Map from {@link Entity.id} to Euler angles in degrees ````[rx, ry, rz]````.
+	 * @returns {Boolean} True if any {@link Entity}s were updated, else false.
+	 */
+	setObjectsRotationMap(rotationMap: { [id: string]: number[] }): boolean;
+
+	/**
+	 * Batch-updates local scale on {@link Entity}s that represent objects.
+	 *
+	 * Only works on Entity types that have a ````scale```` property.
+	 *
+	 * @param {String[]} ids Array of {@link Entity.id} values.
+	 * @param {Number[]} scale 3D scale vector ````[sx, sy, sz]````.
+	 * @returns {Boolean} True if any {@link Entity}s were updated, else false.
+	 */
+	setObjectsScale(ids: string | string[], scale: number[]): boolean;
+
+	/**
+	 * Gets the local scale of an object {@link Entity}.
+	 *
+	 * @param {String} id The {@link Entity.id}.
+	 * @returns {Number[]|null} 3D scale vector ````[sx, sy, sz]````, or ````null````.
+	 */
+	getObjectScale(id: string): number[] | null;
+
+	/**
+	 * Batch-updates local scale on {@link Entity}s, with per-object values.
+	 *
+	 * @param scaleMap Map from {@link Entity.id} to 3D scale vector ````[sx, sy, sz]````.
+	 * @returns {Boolean} True if any {@link Entity}s were updated, else false.
+	 */
+	setObjectsScaleMap(scaleMap: { [id: string]: number[] }): boolean;
+
+	/**
+	 * Batch-updates local rotation quaternion on {@link Entity}s that represent objects.
+	 *
+	 * Only works on Entity types that have a ````quaternion```` property.
+	 *
+	 * @param {String[]} ids Array of {@link Entity.id} values.
+	 * @param {Number[]} quaternion Quaternion ````[x, y, z, w]````.
+	 * @returns {Boolean} True if any {@link Entity}s were updated, else false.
+	 */
+	setObjectsQuaternion(ids: string | string[], quaternion: number[]): boolean;
+
+	/**
+	 * Gets the local rotation quaternion of an object {@link Entity}.
+	 *
+	 * @param {String} id The {@link Entity.id}.
+	 * @returns {Number[]|null} Quaternion ````[x, y, z, w]````, or ````null````.
+	 */
+	getObjectQuaternion(id: string): number[] | null;
+
+	/**
+	 * Batch-updates local rotation quaternion on {@link Entity}s, with per-object values.
+	 *
+	 * @param quaternionMap Map from {@link Entity.id} to quaternion ````[x, y, z, w]````.
+	 * @returns {Boolean} True if any {@link Entity}s were updated, else false.
+	 */
+	setObjectsQuaternionMap(quaternionMap: { [id: string]: number[] }): boolean;
+
+	/**
+	 * Batch-updates local modeling transform matrix on {@link Entity}s that represent objects.
+	 *
+	 * Only works on Entity types that have a ````matrix```` property.
+	 *
+	 * @param {String[]} ids Array of {@link Entity.id} values.
+	 * @param {Number[]} matrix 16-element 4x4 column-major matrix.
+	 * @returns {Boolean} True if any {@link Entity}s were updated, else false.
+	 */
+	setObjectsMatrix(ids: string | string[], matrix: number[]): boolean;
+
+	/**
+	 * Gets the local modeling transform matrix of an object {@link Entity}.
+	 *
+	 * @param {String} id The {@link Entity.id}.
+	 * @returns {Number[]|null} 16-element 4x4 column-major matrix, or ````null````.
+	 */
+	getObjectMatrix(id: string): number[] | null;
+
+	/**
+	 * Batch-updates local modeling transform matrix on {@link Entity}s, with per-object values.
+	 *
+	 * @param matrixMap Map from {@link Entity.id} to 16-element 4x4 column-major matrix.
+	 * @returns {Boolean} True if any {@link Entity}s were updated, else false.
+	 */
+	setObjectsMatrixMap(matrixMap: { [id: string]: number[] }): boolean;
+
+	/**
+	 * Gets the World-space matrix of an object {@link Entity}.
+	 *
+	 * @param {String} id The {@link Entity.id}.
+	 * @returns {Number[]|null} 16-element 4x4 column-major World matrix, or ````null````.
+	 */
+	getObjectWorldMatrix(id: string): number[] | null;
+
+	/**
+	 * Gets the World-space axis-aligned bounding box of an object {@link Entity}.
+	 *
+	 * @param {String} id The {@link Entity.id}.
+	 * @returns {Float64Array|number[]|null} Six-element AABB, or ````null````.
+	 */
+	getObjectAABB(id: string): number[] | null;
+
 	/**
 	 * Iterates with a callback over {@link Entity}s that represent objects.
 	 *
@@ -912,4 +1066,3 @@ export declare class Scene extends Component {
 	 */
 	destroy(callback?: Function): void;
 }
-