工具

关于 @realsee/Dnalogel 中的工具函数/类 的文档

导入

import { import UtilUtil } from '@realsee/dnalogel'

Util.blink

闪烁一个 dom / THREE.Object3D

const const target: HTMLElementtarget = var document: Document
MDN Referencedocument.Document.getElementById(elementId: string): HTMLElement | null
Returns a reference to the first object with the specified value of the ID attribute.
@param
elementId String that specifies the ID value.getElementById('my-dom-element')!

import UtilUtil.function blink(objects: Target | Target[], animeOptions?: Util.BlinkAnimeOptions | undefined): Util.AnimeInstance
export blink
@description
闪烁一个物体/Dom@param
animeOptions https://animejs.com/documentation/@example
// 闪烁 three 物体
blink(object3D, { updateRender: () => { five.needsRender = true } })
// 闪烁 dom 5 次
blink(document.getElementById('id'), { loop: 5 * 2 })blink(const target: HTMLElementtarget)
import UtilUtil.function reblink(objects: Target | Target[], animeOptions?: Util.BlinkAnimeOptions | undefined): Util.AnimeInstance
export reblink
@description
闪烁一个不可见的物体/Dom
适用于物体/Dom在初始状态不可见的情况，闪烁完成后的状态为初始不可见的状态@param
animeOptions https://animejs.com/documentation/reblink(const target: HTMLElementtarget) // 反向闪烁

Util.FiveDomEvents

five空间中的物体的交互系统

const const domEvents: Util.FiveDomEventsdomEvents = new import UtilUtil.constructor FiveDomEvents(five: Five, config?: Util.EventHandlerConfig | undefined): Util.FiveDomEventsFiveDomEvents(const five: Fivefive)

const domEvents: Util.FiveDomEventsdomEvents.FiveDomEvents.addEventListener<"click">(object: Object3DWithEvent, event: "click", callback: (event: Util.FiveDomEvent) => boolean | void, config?: Util.EventHandlerConfig | undefined): void
@description
: add event listener@param
params.object : object@param
params.event : event name@param
params.callback : 返回 false 可以不阻止 five 的 tap 事件; default: true@returnaddEventListener(const object: THREE.Object3Dobject, 'click', () => {
  var console: Consoleconsole.Console.log(...data: any[]): void
MDN Referencelog('Clicked!')
})

const domEvents: Util.FiveDomEventsdomEvents.FiveDomEvents.addEventListener<"hover">(object: Object3DWithEvent, event: "hover", callback: (event: Util.FiveDomEvent) => void, config?: Util.EventHandlerConfig | undefined): void
@description
: add event listener@param
params.object : object@param
params.event : event name@param
params.callback : 返回 false 可以不阻止 five 的 tap 事件; default: true@returnaddEventListener(const object: THREE.Object3Dobject, 'hover', () => {
  var console: Consoleconsole.Console.log(...data: any[]): void
MDN Referencelog('Hovered!')
})

const domEvents: Util.FiveDomEventsdomEvents.FiveDomEvents.addEventListener<"unHover">(object: Object3DWithEvent, event: "unHover", callback: (event: Util.FiveDomEvent) => void, config?: Util.EventHandlerConfig | undefined): void
@description
: add event listener@param
params.object : object@param
params.event : event name@param
params.callback : 返回 false 可以不阻止 five 的 tap 事件; default: true@returnaddEventListener(const object: THREE.Object3Dobject, 'unHover', () => {
  var console: Consoleconsole.Console.log(...data: any[]): void
MDN Referencelog('Unhovered!')
})

Util.FivePuppet

使用独立 canvas 绘制物体，摄像机位置及视角与 five 保持一致

const const fivePuppet: Util.FivePuppetfivePuppet = new import UtilUtil.constructor FivePuppet(five: Five, params?: {
    zIndex: number;
} | undefined): Util.FivePuppet
@description
模拟 Five 行为的 canvas，与 Five 唯一区别是 scene 是空的@usecase
当需 five 的 canvas 上层有一些额外的 Dom 元素比如平面图时，希望在这些 Dom 元素上层再绘制一些三维物体，可以
使用 FivePuppet，将要渲染的物体加入到 FivePuppet 的 scene 中即可。甚至可以是原本在 five 中的物体，可以使
用 .clone() 将物体克隆一份然后加入到 FivePuppet 的 scene 中。@example
react
import { Util } from '@realsee/dnalogel'

function App() {
const fivePuppet = React.useRef<Util.FivePuppet>()
const five = unsafe__useFiveInstance()

React.useEffect(() => {
fivePuppet.current = new Util.FivePuppet(five, { zIndex: 20 })

const object = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshBasicMaterial({ color: 0xff0000 }))
fivePuppet.current.scene.add(object)

return () => {
fivePuppet.current?.destory()
}
}, [five])
}@example
javascript
import { Util } from '@realsee/dnalogel'

const five = new Five({
plugins: [
[(five) => new Util.FivePuppet(five), 'fivePuppet']
],
})

const object = new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshBasicMaterial({ color: 0xff0000 }))
five.plugins.fivePuppet.scene.add(object)FivePuppet(const five: Fivefive)
const fivePuppet: Util.FivePuppetfivePuppet.FivePuppet.scene: THREE.Scenescene.Object3D.add(...object: THREE.Object3D[]): THREE.Scene
Adds object as child of this object.add(const object: THREE.Object3Dobject)

Util.lookObject

以最佳视角观察一个物体

import UtilUtil.function lookObject(five: Five, object: THREE.Object3D, config?: {
    scale?: number | undefined;
} | undefined): Promise<void>
@description
以最佳视角观察物体@param
five five 实例@param
object 要观察的物体@param
config.scale 值越大离物体越远，建议范围为 1~2 之间，默认值为 1.4lookObject(const five: Fivefive, const object: THREE.Object3Dobject)

Util.lookPoint

以最佳视角看向一个坐标点

import UtilUtil.function lookPoint(five: Five, point: THREE.Vector3, config?: {
    distance?: number | undefined;
} | undefined): Promise<void>
@description
以最佳视角看向一个三维空间点@param
five five 实例@param
point 要观察的坐标点@param
config.distance 观察距离，单位为米，默认为 3lookPoint(const five: Fivefive, const vector3: THREE.Vector3vector3)

Util.PointSelector

选点器，支持触摸屏长按选点

const const selector: Util.PointSelectorselector = new import UtilUtil.constructor PointSelector(five: Five, config?: Partial<Config> | undefined): Util.PointSelector
@description
: 在屏幕上选点PointSelector(const five: Fivefive)

// 连续选点
const selector: Util.PointSelectorselector.Subscribe<EventMap>.on<"select">(name: "select", callback: (intersection: Util.PointIntersection) => void, once?: boolean | undefined): () => void
注册事件
@param
name - 事件类型@param
callback - 事件回调函数@param
once - 是否只执行一次@returns
解除事件@template
K - 预设的监听事件名称@template
C - 回调函数函数上下文on('select', ({ point: THREE.Vector3
焦点坐标point }) => {
  var console: Consoleconsole.Console.log(...data: any[]): void
MDN Referencelog('Selected point:', point: THREE.Vector3
焦点坐标point)
})

// 选点后自动结束
const selector: Util.PointSelectorselector.Subscribe<EventMap>.on<"select">(name: "select", callback: (intersection: Util.PointIntersection) => void, once?: boolean | undefined): () => void
注册事件
@param
name - 事件类型@param
callback - 事件回调函数@param
once - 是否只执行一次@returns
解除事件@template
K - 预设的监听事件名称@template
C - 回调函数函数上下文on('select', ({ point: THREE.Vector3
焦点坐标point }) => {
  var console: Consoleconsole.Console.log(...data: any[]): void
MDN Referencelog('Selected point:', point: THREE.Vector3
焦点坐标point)
  const selector: Util.PointSelectorselector.PointSelector.disable(): voiddisable()
})

const selector: Util.PointSelectorselector.PointSelector.enable(): voidenable()

Util.sculpt

封装了一些常用的 mesh。完整数据结构：data

const {
  const LineMesh: typeof Util.sculpt.LineMeshLineMesh,
  const BoxMesh: typeof Util.sculpt.BoxMeshBoxMesh,
  const CircleMesh: typeof Util.sculpt.CircleMeshCircleMesh,
  const CircleWithEdgeMesh: typeof Util.sculpt.CircleWithEdgeMeshCircleWithEdgeMesh,
  const CylinderMesh: typeof Util.sculpt.CylinderMeshCylinderMesh,
  const PointMesh: typeof Util.sculpt.PointMeshPointMesh,
  const PolygonMesh: typeof Util.sculpt.PolygonMeshPolygonMesh,
  const PrismMesh: typeof Util.sculpt.PrismMeshPrismMesh
} = import UtilUtil.import sculptsculpt

// 在空间中添加 (0,1,2) 点
const five: Fivefive.Five.scene: Scene
内部使用的 THREE.Scenescene.Scene.add(...objects: AddableObject[]): Scene
Adds object as child of this object.add(new const PointMesh: new (params?: Partial<ColorStyle & {
    size: number;
} & OcclusionStyle & Partial<DisplayInfoConfig> & PointData> | undefined) => Util.sculpt.PointMeshPointMesh({ point?: AnyPosition | undefinedpoint: [0, 1, 2] }))

// 添加线
const five: Fivefive.Five.scene: Scene
内部使用的 THREE.Scenescene.Scene.add(...objects: AddableObject[]): Scene
Adds object as child of this object.add(new const LineMesh: new (params?: Partial<LineColorStyle & LineOpacityStyle & LineWidthStyle & {
    dashed?: boolean | undefined;
} & OcclusionStyle & Partial<...> & Partial<...> & PointsData> | undefined) => Util.sculpt.LineMeshLineMesh({ points?: AnyPosition[] | undefinedpoints: [[0, 1, 2], [3, 4, 5]] }))

// 添加多边形
const five: Fivefive.Five.scene: Scene
内部使用的 THREE.Scenescene.Scene.add(...objects: AddableObject[]): Scene
Adds object as child of this object.add(new const PolygonMesh: new (params?: Partial<OpacityStyle & ColorStyle & OcclusionStyle & {
    lengthEnable: boolean;
} & PointsData> | undefined) => Util.sculpt.PolygonMeshPolygonMesh({ points?: AnyPosition[] | undefinedpoints: [[0, 1, 2], [3, 4, 5], [6, 7, 8]] }))

// 添加半径为3的圆，圆心为 (0,1,2) 点
const five: Fivefive.Five.scene: Scene
内部使用的 THREE.Scenescene.Scene.add(...objects: AddableObject[]): Scene
Adds object as child of this object.add(new const CircleMesh: new (params?: Partial<OpacityStyle & ColorStyle & OcclusionStyle & CircleData> | undefined) => Util.sculpt.CircleMeshCircleMesh({ center?: AnyPosition | undefinedcenter: [0, 1, 2], radius?: number | undefinedradius: 3 }))

// 添加带边的圆
const five: Fivefive.Five.scene: Scene
内部使用的 THREE.Scenescene.Scene.add(...objects: AddableObject[]): Scene
Adds object as child of this object.add(new const CircleWithEdgeMesh: new (params?: Partial<OpacityStyle & ColorStyle & OcclusionStyle & LineColorStyle & LineOpacityStyle & LineWidthStyle & CircleData> | undefined) => Util.sculpt.CircleWithEdgeMeshCircleWithEdgeMesh({ center?: AnyPosition | undefinedcenter: [0, 1, 2], radius?: number | undefinedradius: 3 }))

// 添加柱体
const five: Fivefive.Five.scene: Scene
内部使用的 THREE.Scenescene.Scene.add(...objects: AddableObject[]): Scene
Adds object as child of this object.add(new const CylinderMesh: new (params?: Partial<OpacityStyle & ColorStyle & OcclusionStyle & LineColorStyle & LineOpacityStyle & LineWidthStyle & CylinderData> | undefined) => Util.sculpt.CylinderMeshCylinderMesh({ bottomCenter?: AnyPosition | undefinedbottomCenter: [0, 1, 0], topCenter?: AnyPosition | undefinedtopCenter: [0, 2, 0], radius?: number | undefinedradius: 3 }))

// 添加 box，底面矩形为 [[0, 0, 0], [1, 0, 0], [1, 0, 1], [0, 0, 1]]，高点为 [0, 2, 0]
const five: Fivefive.Five.scene: Scene
内部使用的 THREE.Scenescene.Scene.add(...objects: AddableObject[]): Scene
Adds object as child of this object.add(new const BoxMesh: new (params?: Partial<PrismData & OpacityStyle & ColorStyle & OcclusionStyle & LineColorStyle & LineOpacityStyle & LineWidthStyle> | undefined) => Util.sculpt.BoxMeshBoxMesh({ 
  points?: AnyPosition[] | undefinedpoints: [
    [0, 0, 0],
    [1, 0, 0],
    [1, 0, 1],
    [0, 0, 1]
  ],
  heightPoint?: AnyPosition | undefinedheightPoint: [0, 2, 0], 
}))

// 添加棱柱
const five: Fivefive.Five.scene: Scene
内部使用的 THREE.Scenescene.Scene.add(...objects: AddableObject[]): Scene
Adds object as child of this object.add(new const PrismMesh: new (params?: Partial<PrismData & OpacityStyle & ColorStyle & OcclusionStyle & LineColorStyle & LineOpacityStyle & LineWidthStyle> | undefined) => Util.sculpt.PrismMeshPrismMesh({
  points?: AnyPosition[] | undefinedpoints: [
    [0, 0, 0],
    [1, 0, 0],
    [1, 0, 2],
    [1, 0, 1],
    [0, 0, 1]
  ],
  heightPoint?: AnyPosition | undefinedheightPoint: [0, 2, 0], 
}))

其他的一些用法：Sculpt (e.g.: 绘制一个 boxMesh 并启用 box 编辑功能)

const { const PointSelector: typeof Util.PointSelectorPointSelector } = import UtilUtil
const { const BoxMesh: typeof Util.sculpt.BoxMeshBoxMesh, const BoxMeshEditor: typeof Util.sculpt.BoxMeshEditorBoxMeshEditor, const createBox: (boxMesh: Util.sculpt.BoxMesh, pointSelector: Util.PointSelector, config?: Partial<CreateLimitConfig & DrawMethodConfig> | undefined) => Promise<void>createBox } = import UtilUtil.import sculptsculpt

// 创建 boxMesh
const const boxMesh: Util.sculpt.BoxMeshboxMesh = new const BoxMesh: new (params?: Partial<PrismData & OpacityStyle & ColorStyle & OcclusionStyle & LineColorStyle & LineOpacityStyle & LineWidthStyle> | undefined) => Util.sculpt.BoxMeshBoxMesh({ lineColor?: Color | undefined
@description
: 边框线颜色@default
0xfffffflineColor: 0xff0000 })
const five: Fivefive.Five.scene: Scene
内部使用的 THREE.Scenescene.Scene.add(...objects: AddableObject[]): Scene
Adds object as child of this object.add(const boxMesh: Util.sculpt.BoxMeshboxMesh)

// 按需初始化编辑器
const const editor: Util.sculpt.BoxMeshEditoreditor = new const BoxMeshEditor: new (boxMesh: Util.sculpt.BoxMesh) => Util.sculpt.BoxMeshEditorBoxMeshEditor(const boxMesh: Util.sculpt.BoxMeshboxMesh)

// 创建选择器
const const pointSelector: Util.PointSelectorpointSelector = new const PointSelector: new (five: Five, config?: Partial<Config> | undefined) => Util.PointSelectorPointSelector(const five: Fivefive)

const createBox: (boxMesh: Util.sculpt.BoxMesh, pointSelector: Util.PointSelector, config?: Partial<CreateLimitConfig & DrawMethodConfig> | undefined) => Promise<...>createBox(const boxMesh: Util.sculpt.BoxMeshboxMesh, const pointSelector: Util.PointSelectorpointSelector).Promise<void>.then<void, never>(onfulfilled?: ((value: void) => void | PromiseLike<void>) | null | undefined, onrejected?: ((reason: any) => PromiseLike<never>) | null | undefined): Promise<...>
Attaches callbacks for the resolution and/or rejection of the Promise.
@param
onfulfilled The callback to execute when the Promise is resolved.@param
onrejected The callback to execute when the Promise is rejected.@returns
A Promise for the completion of which ever callback is executed.then(() => {
  var console: Consoleconsole.Console.log(...data: any[]): void
MDN Referencelog('绘制完成')

  // 按需启用编辑功能
  const editor: Util.sculpt.BoxMeshEditoreditor.BaseEditorWithObjectHelper<BoxMesh>.enable(): void
@description
: 开启编辑器enable()
})

Util.tag

轻量化的标签

const const tag1: Util.LightTagtag1 = import UtilUtil.function tag(five: Five, position?: AnyPosition | undefined, config?: {
    wrapper?: HTMLElement | undefined;
    positionsForRotate?: AnyPosition[] | undefined;
    namespace?: string | undefined;
} | undefined): Util.LightTagtag(const five: Fivefive, [0, 1, 2])
const tag1: Util.LightTagtag1.LightTag.container: HTMLDivElement
@description
单个标签 domcontainer.InnerHTML.innerHTML: string
MDN ReferenceinnerHTML = '<div>tag1</div>'

const const tag2: Util.LightTagtag2 = import UtilUtil.function tag(five: Five, position?: AnyPosition | undefined, config?: {
    wrapper?: HTMLElement | undefined;
    positionsForRotate?: AnyPosition[] | undefined;
    namespace?: string | undefined;
} | undefined): Util.LightTagtag(const five: Fivefive, [0, 1, 2])
const tag2: Util.LightTagtag2.LightTag.container: HTMLDivElement
@description
单个标签 domcontainer.InnerHTML.innerHTML: string
MDN ReferenceinnerHTML = '<div>tag2</div>'

或：先初始化，后设置位置

const const tag: Util.LightTagtag = import UtilUtil.function tag(five: Five, position?: AnyPosition | undefined, config?: {
    wrapper?: HTMLElement | undefined;
    positionsForRotate?: AnyPosition[] | undefined;
    namespace?: string | undefined;
} | undefined): Util.LightTagtag(const five: Fivefive)
const tag: Util.LightTagtag.LightTag.container: HTMLDivElement
@description
单个标签 domcontainer.InnerHTML.innerHTML: string
MDN ReferenceinnerHTML = '<div>tag</div>'

const tag: Util.LightTagtag.LightTag.setPosition(position: AnyPosition, positionsForRotate?: AnyPosition[] | undefined): void
@description
设置标签位置@param
position 位置@param
positionsForRotate 用于 css 旋转的斜线的两个端点setPosition(new import THREETHREE.constructor Vector3(x?: number | undefined, y?: number | undefined, z?: number | undefined): THREE.Vector3
3D vector.
@example
var a = new THREE.Vector3( 1, 0, 0 );
var b = new THREE.Vector3( 0, 1, 0 );
var c = new THREE.Vector3();
c.crossVectors( a, b );@see
{@link https://github.com/mrdoob/three.js/blob/master/src/math/Vector3.js src/math/Vector3.js}( class Vector3 implements Vector )Vector3(0, 1, 2))