Class: Glyphset

Glyphset() → {Glyphset}

new Glyphset() → {Glyphset}

This is a container of Glyph and their graphical properties including transformations, colors, number of time steps, duration of animations and group name. Please note that all glyphs in the glyphset share the same geometry however they may have different transformations.
Author:
  • Alan Wu
Source:
Returns:
Type
Glyphset

Methods

addCustomGlyph(Glyph)

Add a custom Glyph to this Glyphset.
Parameters:
Name Type Description
Glyph Glyph to be added.
Source:

addMeshAsGlyph(Mesh, id)

Add a THREE.Mesh object to be displayed as glyph in this Glyphset.
Parameters:
Name Type Description
Mesh THREE.Mesh to be added.
id Number of the mesh.
Source:

canShowLabel()

Check whether label can be shown
Source:

clearColorExportState()

Undoes prepareColorForExport() - see its comment for why this matters: without it, the next live render would permanently pick up the stale instanceColor multiply bug this whole design avoids.
Source:

dispose()

Clear this glyphset and its list of glyphs which will release them from the memory.
Source:

forEachGlyph(callbackFunction)

A function which iterates through the list of glyphs and call the callback function with the glyph as the argument.
Parameters:
Name Type Description
callbackFunction function Callback function with the glyph as an argument.
Source:

getBoundingBox() → {Three.Box3}

Get the bounding box for the whole set of glyphs.
Source:
Returns:
;
Type
Three.Box3

getClosestVertex()

Get the closest vertex to centroid.
Source:

getClosestVertexIndex()

Get the index of the closest vertex to centroid.
Source:

getCurrentTime() → {Number}

Get the current inbuild time of the
Source:
Returns:
Type
Number

getLabel()

Get the assigned label for instance at index
Source:

hideLabel()

Hide label with the choosen colour.
Source:

isTimeVarying() → {Boolean}

Check if the glyphset is time varying.
Source:
Returns:
Type
Boolean

isUsingGPUCompute() → {Boolean}

Check if the glyph transforms are animated on the GPU.
Source:
Returns:
Type
Boolean

load(glyphsetData, glyphURL, finishCallback)

Copy glyphset data into this glyphset then load the glyph's geoemtry with the provided glyphURL. FinishCallback will be called once glyph is loaded.
Parameters:
Name Type Description
glyphsetData Array contains the informations about the glyphs.
glyphURL String URL to the geometry which will be applied to all all the glyphs in the glyphset once loaded.
finishCallback function User's function to be called once glyph's geometry is loaded.
Source:

prepareColorForExport() → {Promise}

Exporters (see sceneExporter.js/GLTFExporter.js) read THREE.InstancedMesh.instanceColor directly off this.morph - which createGlyphs() intentionally leaves null whenever colour is glyphCompute-driven. No-op for glyphsets whose colour isn't glyphCompute-driven (instanceColor there is already accurate, ordinary CPU-driven state).
Source:
Returns:
Type
Promise

render()

Update the glyphsets if required the render.
Source:

setMorphTime(time)

Set the local time of this glyphset.
Parameters:
Name Type Description
time Number Can be any value between 0 to duration.
Source:

setScaleAll() → {THREE.Box3}

Set the objects scale.
Source:
Returns:
.
Type
THREE.Box3

showLabel()

Display the label of the glyphs in the glyphset.
Source:

(inner) applyGlyphComputeResult()

Writes back a GPU glyph-transform compute readback (see dispatchGlyphCompute) into instanceMatrix/instanceColor - i.e. exactly the data updateGlyphsetTransformation()/updateGlyphsetHexColors() write on the CPU path, so bounding box/raycast/getClosestVertex keep working completely unchanged downstream.
Source:

(inner) computeAllFramesBoundingBox()

Computes a single Box3 that conservatively contains every keyframe's exact per-instance transform of the base glyph geometry, for use as getBoundingBox()'s answer while boundsAreExact is false (see its declaration above for the caveat on this not being a formally proven bound). One-time cost at load, reusing resolve_glyph_axes() the same way updateGlyphsetTransformation() does, just for every keyframe instead of just the current one, unioned together.
Source:

(inner) createGlyphs(displayLabels)

Create the glyphs in the glyphset.
Parameters:
Name Type Description
displayLabels Boolean Flag to determine either the labels should be display or not.
Source:

(inner) dispatchGlyphCompute()

Kicks off (at most one in flight at a time) an async GPU compute + readback for the current bottom/top frame + proportion. If a previous dispatch is still resolving, this frame's update is skipped rather than queued - the next call to updateMorphGlyphsets() will dispatch with whatever bottom/top/proportion is current *then*, so playback can't fall further and further behind, at the cost of the displayed state lagging the true target time by about one frame while animating.
Source:

(inner) dispatchGlyphComputeFast()

The fast per-frame path used while actively playing: only dispatches the compute pass (updating the GPU buffers the render material reads directly - see ../tsl/glyphRenderMaterial.js) with no CPU readback at all, bouding box will not be updated.
Source:

(inner) flattenColorFrames()

Same as flattenVec3Frames but for the colours object, whose per-frame values are one packed hex int per glyph rather than 3 raw components - decode each into RGB floats up front so the compute shader only ever deals with plain vec3s.
Source:

(inner) flattenVec3Frames()

Flattens a { "0": [x,y,z,...], "1": [...], ... } per-keyframe object (as used for axis1/axis2/axis3/positions/scale) into one contiguous [time][record][xyz] buffer for the GPU compute path.
Source:

(inner) readbackGlyphComputeOnly()

The readback half of the debounced accurate resync (see scheduleAccurateResync): unlike dispatchGlyphCompute(), this does NOT call renderer.compute() first - by the time this fires, the buffers already hold the right result.
Source:

(inner) resolve_glyph_axes() → {Array}

Calculate the actual transformation value that can be applied to the transformation matrix.
Source:
Returns:
Type
Array

(inner) scheduleAccurateResync()

(Re)schedules a single accurate resync ACCURATE_RESYNC_DEBOUNCE_MS from now, cancelling any previously scheduled one.
Source:

(inner) updateGlyphsetHexColors(current_colors, labelsOnly)

Update colour for each of the glyph in this glyphset.
Parameters:
Name Type Description
current_colors Array one hex value per raw (pre-repeat_mode- expansion) glyph record.
labelsOnly Boolean when true, only glyph labels are recoloured - instanceColor is left untouched (not even created). Used for the initial load-time colour of GPU-compute-driven glyphsets (see createGlyphs()): instanceColor must stay uncreated there (see applyGlyphComputeResult's comment on the NodeMaterial double-multiply this avoids), but labels aren't part of the compute-buffer render path at all and would otherwise show no colour until the first accurate resync.
Source:

(inner) updateGlyphsetTransformation()

Update transformation for each of the glyph in this glyphset.
Source:

(inner) updateMorphGlyphsets(debounceAccurateResync)

Update the current states of the glyphs in this glyphset, this includes transformation and colour for each of them. This is called when glyphset and glyphs are initialised and whenever the internal time has been updated.
Parameters:
Name Type Description
debounceAccurateResync Boolean When true the costlier GPU->CPU readback (bounding box/raycast/ export accuracy - see dispatchGlyphCompute) is debounced until updates have been quiet for ACCURATE_RESYNC_DEBOUNCE_MS. When false/omitted (e.g. the render loop's animation-just-stopped resync), the readback happens immediately, as before.
Source:

(inner) writeTransformMatrix()

Writes a resolve_glyph_axes() result tuple [point, axis1, axis2, axis3] into a THREE.Matrix4's .elements, matching the column-major axis1/axis2/axis3/point layout instanceMatrix expects.
Source: