工具

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

导入

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

Util.blink

闪烁一个 dom / THREE.Object3D

const const target: HTMLElementtarget = var document: Document
window.document returns a reference to the document contained in the window.
MDN Referencedocument.Document.getElementById(elementId: string): HTMLElement | null
The getElementById() method of the Document interface returns an Element object representing the element whose id property matches the specified string. Since element IDs are required to be unique if specified, they're a useful way to get access to a specific element quickly.getElementById('my-dom-element')!

import UtilUtil.
function blink(objects: Util.Target | Util.Target[], animeOptions?: Util.BlinkAnimeOptions): Util.AnimeInstance
export blink
闪烁一个物体或DOM元素
@description
为指定的 js 对象或 DOM 元素创建闪烁动画效果。
动画会自动保存物体的初始状态，并在动画结束后恢复到初始状态。@param
objects - 要闪烁的目标对象或对象数组@param
animeOptions - 动画选项配置@returns
动画实例，可以用于控制动画@example
// 闪烁 js 对象
const animeInstance = blink(object3D, {
  updateRender: () => { five.needsRender = true }
})

// 闪烁 DOM 元素 5 次
blink(document.getElementById('id'), {
  loop: 5 * 2
})

// 自定义动画参数
blink(object3D, {
  duration: 500,
  easing: 'easeInOutQuad',
  loop: 6,
  updateRender: () => renderer.render(scene, camera)
})@example
// 提前结束动画
const anime = blink(object3D)
setTimeout(() => {
  anime.preComplete() // 立即结束动画并恢复状态
}, 1000)blink(const target: HTMLElementtarget)
import UtilUtil.
function reblink(objects: Util.Target | Util.Target[], animeOptions?: Util.ReBlinkAnimeOptions): Util.AnimeInstance
export reblink
闪烁一个不可见的物体或DOM元素
@description
适用于物体或DOM元素在初始状态不可见的情况。
闪烁完成后的状态为初始不可见的状态。@param
objects - 要闪烁的目标对象或对象数组@param
animeOptions - 动画选项配置@returns
动画实例，可以用于控制动画@example
// 闪烁不可见的 js 对象
reblink(invisibleObject3D, {
  maxOpacity: 0.8,
  updateRender: () => { five.needsRender = true }
})

// 闪烁隐藏的 DOM 元素
reblink(hiddenElement, {
  duration: 1000,
  loop: 3
})@example
// 自定义最大透明度
reblink(object3D, {
  maxOpacity: 0.5, // 最大透明度为 0.5
  duration: 500,
  easing: 'easeInOutQuad'
})reblink(const target: HTMLElementtarget) // 反向闪烁

Util.FiveDomEvents

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

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

const domEvents: Util.FiveDomEventsdomEvents.FiveDomEvents.addEventListener<"click">(object: Object3DWithEvent, event: "click", callback: (event: Util.FiveDomEvent) => boolean | void, config?: Omit<Util.EventHandlerConfig, "fiveModels">): 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
The console.log() static method outputs a message to the console.
MDN Referencelog('Clicked!')
})

const domEvents: Util.FiveDomEventsdomEvents.FiveDomEvents.addEventListener<"hover">(object: Object3DWithEvent, event: "hover", callback: (event: Util.FiveDomEvent) => void, config?: Omit<Util.EventHandlerConfig, "fiveModels">): 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
The console.log() static method outputs a message to the console.
MDN Referencelog('Hovered!')
})

const domEvents: Util.FiveDomEventsdomEvents.FiveDomEvents.addEventListener<"unHover">(object: Object3DWithEvent, event: "unHover", callback: (event: Util.FiveDomEvent) => void, config?: Omit<Util.EventHandlerConfig, "fiveModels">): 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
The console.log() static method outputs a message to the console.
MDN Referencelog('Unhovered!')
})

Util.FivePuppet

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

const const fivePuppet: Util.FivePuppetfivePuppet = new import UtilUtil.
constructor FivePuppet(five: Five, params?: {
    zIndex: number;
}): 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;
    minDistance?: number;
    minLatitude?: number;
}): Promise<void>
@description
以最佳视角观察物体@param
five five 实例@param
object 要观察的物体@param
config.scale 值越大离物体越远，建议范围为 1~2 之间，默认值为 1.4@param
config.minDistance 最小观察距离，如果计算出的距离小于此值，则使用此值@param
config.minLatitude 最小纬度角（弧度），如果计算出的纬度小于此值，则调整相机位置lookObject(const five: Fivefive, const object: THREE.Object3Dobject)

Util.lookPoint

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

import UtilUtil.
function lookPoint(five: Five, point: THREE.Vector3, config?: {
    distance?: number;
}): 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?: Util.PointSelectorConfig): Util.PointSelector
@description
: 在屏幕上选点PointSelector(const five: Fivefive)

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

// 选点后自动结束
const selector: Util.PointSelectorselector.Subscribe<EventMap>.on<"select">(name: "select", callback: (intersection?: Util.PointIntersection | null | undefined) => void, once?: boolean): () => void
注册事件
@param
name - 事件类型@param
callback - 事件回调函数@param
once - 是否只执行一次@returns
解除事件@template
K - 预设的监听事件名称@template
C - 回调函数函数上下文on('select', (intersection: Util.PointIntersection | null | undefinedintersection) => {
  var console: Consoleconsole.Console.log(...data: any[]): void
The console.log() static method outputs a message to the console.
MDN Referencelog('Selected point:', intersection: Util.PointIntersection | null | undefinedintersection?.Intersection.point: THREE.Vector3 | undefined
焦点坐标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<PointStyle & PointData>) => 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<LineMeshStyle & LineData>) => 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<PolygonStyle & PolygonData>) => 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>) => 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<CircleWithEdgeMeshStyle & CircleData>) => 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>) => 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 & PrismStyle & {
    five?: Five;
}>) => 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 & PrismStyle & {
    five?: Five;
}>) => 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?: BoxCreateConfig) => Promise<void>createBox } = import UtilUtil.import sculptsculpt

// 创建 boxMesh
const const boxMesh: Util.sculpt.BoxMeshboxMesh = new 
const BoxMesh: new (params?: Partial<PrismData & PrismStyle & {
    five?: Five;
}>) => 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?: Util.PointSelectorConfig) => Util.PointSelectorPointSelector(const five: Fivefive)

const createBox: (boxMesh: Util.sculpt.BoxMesh, pointSelector: Util.PointSelector, config?: BoxCreateConfig) => Promise<void>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<void>
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
The console.log() static method outputs a message to the console.
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;
    positionsForRotate?: AnyPosition[];
    namespace?: string;
    disableOpacityTransition?: boolean;
} | undefined): Util.LightTagtag(const five: Fivefive, [0, 1, 2])
const tag1: Util.LightTagtag1.LightTag.container: HTMLDivElement
@description
单个标签 domcontainer.Element.innerHTML: string
The innerHTML property of the Element interface gets or sets the HTML or XML markup contained within the element, omitting any shadow roots in both cases.
MDN ReferenceinnerHTML = '<div>tag1</div>'

const const tag2: Util.LightTagtag2 = import UtilUtil.
function tag(five: Five, position?: AnyPosition | undefined, config?: {
    wrapper?: HTMLElement;
    positionsForRotate?: AnyPosition[];
    namespace?: string;
    disableOpacityTransition?: boolean;
} | undefined): Util.LightTagtag(const five: Fivefive, [0, 1, 2])
const tag2: Util.LightTagtag2.LightTag.container: HTMLDivElement
@description
单个标签 domcontainer.Element.innerHTML: string
The innerHTML property of the Element interface gets or sets the HTML or XML markup contained within the element, omitting any shadow roots in both cases.
MDN ReferenceinnerHTML = '<div>tag2</div>'

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

const const tag: Util.LightTagtag = import UtilUtil.
function tag(five: Five, position?: AnyPosition | undefined, config?: {
    wrapper?: HTMLElement;
    positionsForRotate?: AnyPosition[];
    namespace?: string;
    disableOpacityTransition?: boolean;
} | undefined): Util.LightTagtag(const five: Fivefive)
const tag: Util.LightTagtag.LightTag.container: HTMLDivElement
@description
单个标签 domcontainer.Element.innerHTML: string
The innerHTML property of the Element interface gets or sets the HTML or XML markup contained within the element, omitting any shadow roots in both cases.
MDN ReferenceinnerHTML = '<div>tag</div>'

const tag: Util.LightTagtag.LightTag.setPosition(position: AnyPosition, positionsForRotate?: AnyPosition[]): void
@description
设置标签位置@param
position 位置@param
positionsForRotate 用于 css 旋转的斜线的两个端点setPosition(new import THREETHREE.constructor Vector3(x?: number, y?: number, z?: number): 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))