@qy_better_lib/hooks 0.2.9 → 0.2.11

package/lib/use-three/interface.d.ts

@@ -0,0 +1,204 @@
+import { ThreeTarget } from '../shared/type';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js';
+import { OutlinePass } from 'three/examples/jsm/postprocessing/OutlinePass.js';
+import { UnrealBloomPass } from 'three/examples/jsm/postprocessing/UnrealBloomPass.js';
+import { BoxHelper, Object3D } from 'three';
+import { ObjectToolTip, ToolTipOptions } from './toolTip';
+import { OutLineOptions } from './type';
+export interface UseThree {
+    /**three 实例*/
+    instance: ThreeTarget;
+    /**
+     * 初始化
+     */
+    init_three: () => void;
+    /**
+     * 设置渲染容器
+     * @param container 渲染容器元素
+     */
+    set_container: (container: HTMLElement) => void;
+    /**
+     * 创建透视相机
+     */
+    create_perspective_camera: () => void;
+    /**
+     * 创建正交相机
+     * @param options 正交相机配置
+     */
+    create_orthographic_camera: (options?: any) => void;
+    /**
+     * 设置相机预设
+     * @param preset 预设名称
+     */
+    set_camera_preset: (preset: 'front' | 'back' | 'top' | 'bottom' | 'left' | 'right') => void;
+    /**
+     * 添加默认光照
+     */
+    add_default_lighting: () => void;
+    /**
+     * 添加环境光
+     * @param options 光源配置
+     */
+    add_ambient_light: (options?: any) => void;
+    /**
+     * 添加平行光
+     * @param options 光源配置
+     */
+    add_directional_light: (options?: any) => void;
+    /**
+     * 添加点光源
+     * @param options 光源配置
+     */
+    add_point_light: (options?: any) => void;
+    /**
+     * 添加聚光灯
+     * @param options 光源配置
+     */
+    add_spot_light: (options?: any) => void;
+    /**
+     * 设置渲染状态
+     * @param status 渲染状态
+     */
+    set_rendering_status: (status: boolean) => void;
+    /**
+     * 设置目标帧率
+     * @param fps 帧率
+     */
+    set_target_fps: (fps: number) => void;
+    /**
+     * 加载GLTF模型
+     * @param url 模型URL
+     * @param options 加载选项
+     * @returns 加载状态对象
+     */
+    load_gltf_model: (url: string, options?: {
+        onProgress?: (progress: number) => void;
+        onError?: (error: any) => void;
+    }) => any;
+    /**
+     * 加载OBJ模型
+     * @param url 模型URL
+     * @param mtlUrl 材质URL
+     * @param options 加载选项
+     * @returns 加载状态对象
+     */
+    load_obj_model: (url: string, mtlUrl?: string, options?: {
+        onProgress?: (progress: number) => void;
+        onError?: (error: any) => void;
+    }) => any;
+    /**
+     * 启用对象拖拽
+     * @param object 要拖拽的对象
+     * @param options 拖拽选项
+     */
+    enable_object_drag: (object: Object3D, options?: {
+        onDragStart?: () => void;
+        onDragEnd?: () => void;
+        onDrag?: (position: {
+            x: number;
+            y: number;
+            z: number;
+        }) => void;
+    }) => void;
+    /**
+     * 禁用对象拖拽
+     */
+    disable_object_drag: () => void;
+    /**
+     * 启用触摸设备支持
+     */
+    enable_touch_support: () => void;
+    /**
+     * 工具函数集合
+     */
+    utils: any;
+    /**
+     * three渲染
+     * @param renderer 渲染器
+     * @param scene 场景
+     * @param camera 相机
+     * @param renderAction 渲染行为
+     */
+    render: (renderAction?: Function) => void;
+    /**
+     * 获取模型点击的对象
+     */
+    get_select_object: (e: any) => any;
+    /**开启VR */
+    enabled_vr: () => void;
+    /**禁用VR */
+    disabled_vr: () => void;
+    /**使用模型解压缩，适用于使用DRAC算法压缩的模型 */
+    use_draco_loader: (gltf_loader: GLTFLoader) => void;
+    /**释放 */
+    dispose_three: () => void;
+    /**复位 */
+    reset: () => void;
+    /**容器大小变更 */
+    resize: () => void;
+    /**开启阴影 */
+    enable_shadow: () => void;
+    /**
+     * 创建3D对象工具提示
+     * @param obj 3D对象
+     * @param options 配置选项
+     * @returns ObjectToolTip实例
+     */
+    create_tool_tip: (obj: Object3D, options?: ToolTipOptions) => ObjectToolTip;
+    /**
+     * 创建ObjectToolTip实例
+     * @returns ObjectToolTip实例
+     */
+    create_tool_tip_instance: () => ObjectToolTip;
+    /**
+     * 创建边界框辅助
+     * @param color 边界框颜色
+     * @returns 边界框辅助对象
+     */
+    create_box_helper: (color?: string) => {
+        helper: BoxHelper;
+        add_to_scene: (scene: any) => void;
+        set_box_frame: (obj: Object3D) => void;
+        set_visible: (visible: boolean) => void;
+        destroy: () => void;
+    };
+    /**
+     * 开启后期处理
+     * @param use_ssao 是否使用SSAO效果
+     * @param ssao_options SSAO配置选项
+     * @returns EffectComposer实例
+     */
+    enable_effect: (use_ssao?: boolean, ssao_options?: {
+        kernel_radius?: number;
+        min_distance?: number;
+        max_distance?: number;
+    }) => EffectComposer | null;
+    /**
+     * 开启FXAA抗锯齿
+     * @param composer 后期处理composer
+     */
+    enable_fxaa: (composer: EffectComposer) => void;
+    /**
+     * 开启辉光光晕效果
+     * @param composer 后期处理composer
+     * @param strength 强度
+     * @param radius 半径
+     * @param threshold 阈值
+     * @returns UnrealBloomPass实例
+     */
+    enable_unreal_bloom: (composer: EffectComposer, strength?: number, radius?: number, threshold?: number) => UnrealBloomPass | null;
+    /**
+     * 开启轮廓高亮
+     * @param composer 后期处理composer
+     * @returns OutlinePass实例
+     */
+    enable_outline: (composer: EffectComposer) => OutlinePass | null;
+    /**
+     * 设置模型高光
+     * @param outline_pass OutlinePass实例
+     * @param objects 需要高光的模型
+     * @param out_line_options 配置
+     */
+    set_out_line: (outline_pass: OutlinePass, objects: Object3D[], out_line_options?: OutLineOptions) => void;
+}

package/lib/use-three/modules/box-helper.d.ts

@@ -0,0 +1,15 @@
+import { BoxHelper, Object3D, Scene } from 'three';
+import { ThreeTarget } from '../../shared/type';
+/**
+ * 边界框辅助 Hook
+ * @param current_three Three.js实例
+ * @param color 边界框颜色
+ * @returns 边界框相关方法
+ */
+export declare function use_box_helper(current_three: ThreeTarget, color?: string): {
+    helper: BoxHelper;
+    add_to_scene: (scene: Scene) => void;
+    set_box_frame: (obj: Object3D) => void;
+    set_visible: (visible: boolean) => void;
+    destroy: () => void;
+};

package/lib/use-three/modules/camera.d.ts

@@ -0,0 +1,15 @@
+import { ThreeOption } from '../type';
+import { ThreeTarget } from '../../shared/type';
+/**
+ * 相机系统 Hook
+ * @param current_three Three.js实例
+ * @returns 相机相关方法
+ */
+export declare function use_camera(current_three: ThreeTarget): {
+    create_perspective_camera: (options: ThreeOption) => void;
+    create_orthographic_camera: (options?: any) => void;
+    set_camera_preset: (preset: "front" | "back" | "top" | "bottom" | "left" | "right") => void;
+    orbit_controls: () => void;
+    axes_helper: (size?: number) => void;
+    reset_camera: (options: ThreeOption) => void;
+};

package/lib/use-three/modules/effect-composer.d.ts

@@ -0,0 +1,45 @@
+import { ThreeTarget } from '../../shared/type';
+import { Object3D } from 'three';
+import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js';
+import { OutlinePass } from 'three/examples/jsm/postprocessing/OutlinePass.js';
+import { ShaderPass } from 'three/examples/jsm/postprocessing/ShaderPass.js';
+import { UnrealBloomPass } from 'three/examples/jsm/postprocessing/UnrealBloomPass.js';
+import { FilmPass } from 'three/examples/jsm/postprocessing/FilmPass.js';
+import { OutLineOptions } from '../type';
+/**
+ * SSAO 配置选项
+ */
+interface SSAOOptions {
+    /** 内核半径 */
+    kernel_radius?: number;
+    /** 最小距离 */
+    min_distance?: number;
+    /** 最大距离 */
+    max_distance?: number;
+}
+/**
+ * 电影效果配置选项
+ */
+interface FilmOptions {
+    /** 颗粒强度 */
+    noise_intensity?: number;
+    /** 灰度模式 */
+    grayscale?: boolean;
+}
+/**
+ * 后期处理 Hook
+ * @param current_three Three.js实例
+ * @returns 后期处理相关方法
+ */
+export declare function use_effect_composer(current_three: ThreeTarget): {
+    enable_effect: (use_ssao?: boolean, ssao_options?: SSAOOptions) => EffectComposer;
+    enable_fxaa: (composer: EffectComposer) => void;
+    enable_unreal_bloom: (composer: EffectComposer, strength?: number, radius?: number, threshold?: number) => UnrealBloomPass | null;
+    enable_outline: (composer: EffectComposer) => OutlinePass | null;
+    set_out_line: (outline_pass: OutlinePass, objects: Object3D[], out_line_options?: OutLineOptions) => void;
+    enable_film_effect: (composer: EffectComposer, options?: FilmOptions) => FilmPass | null;
+    enable_grayscale: (composer: EffectComposer) => ShaderPass | null;
+    update_all_composers_size: () => void;
+    clear_composers: () => void;
+};
+export {};

package/lib/use-three/modules/interaction.d.ts

@@ -0,0 +1,21 @@
+import { Object3D, Object3DEventMap } from 'three';
+import { ThreeTarget } from '../../shared/type';
+/**
+ * 交互系统 Hook
+ * @param current_three Three.js实例
+ * @returns 交互相关方法
+ */
+export declare function use_interaction(current_three: ThreeTarget): {
+    get_select_object: (e: any) => Object3D< Object3DEventMap> | null;
+    enable_object_drag: (object: Object3D, options?: {
+        onDragStart?: () => void;
+        onDragEnd?: () => void;
+        onDrag?: (position: {
+            x: number;
+            y: number;
+            z: number;
+        }) => void;
+    }) => void;
+    disable_object_drag: () => void;
+    enable_touch_support: () => void;
+};

package/lib/use-three/modules/lighting.d.ts

@@ -0,0 +1,15 @@
+import { AmbientLight, DirectionalLight, PointLight, SpotLight } from 'three';
+import { ThreeTarget } from '../../shared/type';
+/**
+ * 光照系统 Hook
+ * @param current_three Three.js实例
+ * @returns 光照相关方法
+ */
+export declare function use_lighting(current_three: ThreeTarget): {
+    add_default_lighting: () => void;
+    add_ambient_light: (options?: any) => AmbientLight;
+    add_directional_light: (options?: any) => DirectionalLight;
+    add_point_light: (options?: any) => PointLight;
+    add_spot_light: (options?: any) => SpotLight;
+    enable_shadow: () => void;
+};

package/lib/use-three/modules/loader.d.ts

@@ -0,0 +1,28 @@
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { ThreeTarget } from '../../shared/type';
+/**
+ * 模型加载系统 Hook
+ * @param current_three Three.js实例
+ * @returns 模型加载相关方法
+ */
+export declare function use_loader(current_three: ThreeTarget): {
+    use_draco_loader: (gltfLoader: GLTFLoader) => void;
+    load_gltf_model: (url: string, options?: {
+        onProgress?: (progress: number) => void;
+        onError?: (error: any) => void;
+    }) => {
+        progress: number;
+        loaded: boolean;
+        error: null;
+        model: any;
+    };
+    load_obj_model: (url: string, mtlUrl?: string, options?: {
+        onProgress?: (progress: number) => void;
+        onError?: (error: any) => void;
+    }) => {
+        progress: number;
+        loaded: boolean;
+        error: null;
+        model: any;
+    };
+};

package/lib/use-three/modules/renderer.d.ts

@@ -0,0 +1,18 @@
+import { ThreeTarget } from '../../shared/type';
+import { ThreeOption } from '../type';
+/**
+ * 渲染系统 Hook
+ * @param current_three Three.js实例
+ * @returns 渲染相关方法
+ */
+export declare function use_renderer(current_three: ThreeTarget): {
+    init_renderer: (options: ThreeOption) => void;
+    init_css2_renderer: () => void;
+    set_rendering_status: (status: boolean) => void;
+    set_target_fps: (fps: number) => void;
+    render: (render_action?: Function) => void;
+    resize: () => void;
+    set_container: (container: HTMLElement) => void;
+    cancel_animation: () => void;
+    get_rendering_status: () => boolean;
+};

package/lib/use-three/modules/resources.d.ts

@@ -0,0 +1,12 @@
+import { Object3D } from 'three';
+import { ThreeTarget } from '../../shared/type';
+/**
+ * 资源管理系统 Hook
+ * @param current_three Three.js实例
+ * @returns 资源管理相关方法
+ */
+export declare function use_resources(current_three: ThreeTarget): {
+    clear_resources: () => void;
+    clear_renderer: () => void;
+    remove_object: (object: Object3D) => void;
+};

package/lib/use-three/modules/utils.d.ts

@@ -0,0 +1,133 @@
+import { Object3D, Vector3, Box3 } from 'three';
+/**
+ * 安全执行函数
+ * @param fn 要执行的函数
+ * @param default_value 默认返回值
+ * @returns 函数执行结果或默认值
+ */
+export declare function safe_execute<T>(fn: () => T, default_value?: T): T | undefined;
+/**
+ * 工具函数集合
+ */
+export declare const three_utils: {
+    /**
+     * 计算对象边界盒
+     * @param object 3D对象
+     * @returns 边界盒对象
+     */
+    compute_bounding_box: (object: Object3D) => Box3 | null | undefined;
+    /**
+     * 计算对象中心点
+     * @param object 3D对象
+     * @returns 中心点坐标
+     */
+    compute_center: (object: Object3D) => Vector3 | undefined;
+    /**
+     * 生成网格辅助线
+     * @param size 网格大小
+     * @param divisions 网格细分
+     * @returns 网格辅助线对象
+     */
+    create_grid_helper: (size?: number, divisions?: number) => any;
+    /**
+     * 创建坐标轴辅助器
+     * @param size 坐标轴大小
+     * @returns 坐标轴辅助器对象
+     */
+    create_axes_helper: (size?: number) => any;
+    /**
+     * 创建立方体
+     * @param size 立方体大小
+     * @param material 材质
+     * @returns 立方体对象
+     */
+    create_box: (size?: number, material?: any) => any;
+    /**
+     * 创建球体
+     * @param radius 球体半径
+     * @param material 材质
+     * @returns 球体对象
+     */
+    create_sphere: (radius?: number, material?: any) => any;
+    /**
+     * 创建圆柱体
+     * @param radius_top 顶部半径
+     * @param radius_bottom 底部半径
+     * @param height 高度
+     * @param material 材质
+     * @returns 圆柱体对象
+     */
+    create_cylinder: (radius_top?: number, radius_bottom?: number, height?: number, material?: any) => any;
+    /**
+     * 屏幕坐标转世界坐标
+     * @param x 屏幕X坐标
+     * @param y 屏幕Y坐标
+     * @param camera 相机
+     * @returns 世界坐标
+     */
+    screen_to_world: (x: number, y: number, camera: any) => any;
+    /**
+     * 世界坐标转屏幕坐标
+     * @param position 世界坐标
+     * @param camera 相机
+     * @returns 屏幕坐标
+     */
+    world_to_screen: (position: Vector3, camera: any) => {
+        x: number;
+        y: number;
+    } | undefined;
+    /**
+     * 平滑动画函数
+     * @param start 起始值
+     * @param end 结束值
+     * @param duration 动画时长
+     * @param callback 每帧回调
+     * @param ease 缓动函数
+     */
+    animate: (start: number, end: number, duration: number, callback: (value: number) => void, ease?: (t: number) => number) => void;
+    /**
+     * 缓动函数集合
+     */
+    easing: {
+        linear: (t: number) => number;
+        ease_in_quad: (t: number) => number;
+        ease_out_quad: (t: number) => number;
+        ease_in_out_quad: (t: number) => number;
+        ease_in_cubic: (t: number) => number;
+        ease_out_cubic: (t: number) => number;
+        ease_in_out_cubic: (t: number) => number;
+    };
+};
+/**相机预设位置 */
+export declare const camera_presets: {
+    front: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    back: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    top: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    bottom: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    left: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    right: {
+        x: number;
+        y: number;
+        z: number;
+    };
+};

package/lib/use-three/toolTip.d.ts

@@ -0,0 +1,101 @@
+import { Object3D, Vector3 } from 'three';
+/**
+ * 3D对象工具提示配置选项
+ */
+export interface ToolTipOptions {
+    /**
+     * 关闭回调函数
+     */
+    onClose?: () => void;
+    /**
+     * 提示框内容
+     */
+    content?: string;
+    /**
+     * 提示框样式类名
+     */
+    className?: string;
+    /**
+     * 提示框位置偏移
+     */
+    offset?: Vector3;
+}
+/**
+ * 3D对象工具提示类
+ * 用于在3D场景中为对象添加交互式工具提示
+ */
+export declare class ObjectToolTip {
+    /**
+     * 关联的3D对象
+     */
+    obj: Object3D | undefined;
+    /**
+     * 工具提示元素
+     */
+    container: HTMLElement | null;
+    /**
+     * CSS2D对象，用于在3D场景中渲染HTML元素
+     */
+    private css2Object;
+    /**
+     * 事件回调
+     */
+    private events;
+    /**
+     * 是否显示
+     */
+    private isVisible;
+    /**
+     * 提示框内容
+     */
+    private content;
+    /**
+     * 创建3D对象工具提示
+     * @param obj 3D对象
+     * @param options 配置选项
+     */
+    create(obj: Object3D, options?: ToolTipOptions): void;
+    /**
+     * 更新提示框内容
+     * @param content 新的内容
+     */
+    updateContent(content: string): void;
+    /**
+     * 更新提示框位置
+     * @param position 新的位置
+     */
+    updatePosition(position: Vector3): void;
+    /**
+     * 显示提示框
+     */
+    show(): void;
+    /**
+     * 隐藏提示框
+     */
+    hide(): void;
+    /**
+     * 移除提示框
+     */
+    remove(): void;
+    /**
+     * 清理资源
+     */
+    private clear;
+    /**
+     * 检查提示框是否可见
+     * @returns 是否可见
+     */
+    isShowing(): boolean;
+    /**
+     * 获取提示框内容
+     * @returns 提示框内容
+     */
+    getContent(): string;
+}
+/**
+ * 创建3D对象工具提示的工厂函数
+ * @param obj 3D对象
+ * @param options 配置选项
+ * @returns ObjectToolTip实例
+ */
+export declare function createObjectToolTip(obj: Object3D, options?: ToolTipOptions): ObjectToolTip;

package/lib/use-three/type.d.ts

@@ -0,0 +1,82 @@
+import { Point3D } from '../shared/type';
+import { Texture } from 'three';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader';
+export type ThreeOption = {
+    /**背景色 */
+    scenebgcolor?: string;
+    /**环境贴图 */
+    scenebg?: Texture;
+    /**相机配置 */
+    camera_option?: CameraOption;
+    /**相机类型，默认为透视相机 */
+    camera_type?: 'perspective' | 'orthographic';
+    /**是否包含控制器 */
+    controls?: boolean;
+    /**坐标辅助器 */
+    axes_helper?: boolean;
+    /**2d html渲染-展示html元素 */
+    css2_render?: boolean;
+    /**开启GPU加速 */
+    gpu?: boolean;
+    /**默认光照设置 */
+    default_lighting?: boolean;
+};
+/**光源配置 */
+export type LightOption = {
+    /**光源颜色 */
+    color?: string | number;
+    /**光源强度 */
+    intensity?: number;
+    /**光源位置 */
+    position?: Point3D;
+};
+/**正交相机配置 */
+export type OrthographicCameraOption = {
+    /**相机位置 */
+    position: Point3D;
+    /**左边界 */
+    left: number;
+    /**右边界 */
+    right: number;
+    /**上边界 */
+    top: number;
+    /**下边界 */
+    bottom: number;
+    /**近截面 */
+    near: number;
+    /**远截面 */
+    far: number;
+};
+/**相机配置 */
+export type CameraOption = {
+    /**相机位置 */
+    position: Point3D;
+    /**摄像机视锥体垂直视野角度，从视图的底部到顶部，以角度来表示。默认值是50 */
+    fov: number;
+    /**摄像机视锥体长宽比 */
+    aspect?: number;
+    /**近距离面 */
+    near: number;
+    /**远局里面 */
+    far: number;
+};
+/**模型加载器 */
+export type ModelLoader = {
+    gltf_loader: GLTFLoader;
+};
+export type OutLineOptions = {
+    /**律动值，数值越大，律动越慢 */
+    pulse_period?: number;
+    /**高光颜色 */
+    visible_edge_color?: string | number;
+    /**阴影颜色 */
+    hidden_edge_color?: string | number;
+    /**是否使用纹理覆盖 */
+    use_pattern_texture?: boolean;
+    /**高光边缘强度 */
+    edge_strength?: number;
+    /**边缘微光强度 */
+    edge_glow?: number;
+    /**高光厚度 */
+    edge_thickness?: number;
+};