API Docs

Class: VolumeArray

PD. VolumeArray

Defines a vector-array-based spatial volume of regularly-spaced data points.

new VolumeArray( [config] [, expansion])

Creates a new vector-array-based regular 3D data grid.

Parameters:
Name Type Argument Description
config object <optional>

An optional configuration object.
Properties of config:
Name Type Argument Description
value any <optional>

The value to initialise all grid cells to.
cells Array.<number> | number <optional>

The number of cells in the grid, either as an array or a number.
min Array.<number> <optional>

The [x,y,z] coordinate array of the minimum extents in each axis.
max Array.<number> <optional>

The [x,y,z] coordinate array of the maximum extents in each axis.
expansion number <optional>

A fraction for the amount of the cell size to expand the extents by (0 to 1), defaults to 0.
config.threshold number <optional>

The default threshold to generate surfaces and voxels at.
config.useCenter Array.<number> | number <optional>

Whether or not to sample values at cell centers instead of at grid points, defaults to false.
Author:
  • drajmarsh

Members

:Float32Array

data

A flat array storing the values at each data point.

Type
  • Float32Array
:number

threshold

The default value at which to generate Iso surfaces and voxel shapes, defaults to 1.

Type
  • number
:number

type

An arbitrary type value defined and used by the host application requirements.

Type
  • number

Methods

_copySurfaceToShape(surfaces [, shape])

Copies generate surface geometry to the given or a new shape.

Parameters:
Name Type Argument Description
surfaces object

The faces and vertices to add.
shape PD.Shape <optional>

The shape to add the surface to, defaults to a new shape if not defined.
Returns:

Returns the shape with the new iso-surface.

Type
PD.Shape

copyIsoToPolyMesh(mesh [, threshold])

Adds an iso-surface shape to a renderable mesh.

The method adds both outlines and surface data.

Parameters:
Name Type Argument Description
mesh PD.PolyMesh

The mesh to add the polygon to.
threshold number <optional>

The value at which to generate the surface.
Returns:

Returns true if geometry was added to the mesh.

Type
boolean

copyVoxelsToPolyMesh(mesh [, threshold])

Adds a voxelised iso-surface shape to a renderable mesh.

The method adds both outlines and surface data.

Parameters:
Name Type Argument Description
mesh PD.PolyMesh

The mesh to add the voxels to.
threshold number <optional>

The value at which to generate voxels.
Returns:

Returns true if geometry was added to the mesh.

Type
boolean

getData(i, j, k)

Retrieves the data stored for the given cell.

This method addresses the 3D grid by numerical index in each axis. Each coordinate is given as the index of the cell in that particular axis. An error is thrown if any index is less than zero or greater than the number of cells in that axis.

Parameters:
Name Type Description
i number

The X-axis index of the cell.
j number

The Y-axis index of the cell.
k number

The Z-axis index of the cell.
Throws:

Throws an error if index is outside array bounds.

Type
Error
Returns:

Returns the data in the given cell.

Type
any

getDataByPos(x, y, z)

Retrieves the linear index of the given cell in the data array.

This method addresses the 3D grid by actual spatial position. Each coordinate is given as an absolute position in space. An error is thrown if the position is outside the spatial extents of the grid.

Whilst cells are arranged in 3 dimensions, the actual data for each cell is stored in a single 1 dimensional array. Use this method to relate 3D grid coordinates to the cell's index in the data array.

Parameters:
Name Type Description
x number

The X-axis position of the cell.
y number

The Y-axis position of the cell.
z number

The Z-axis position of the cell.
Throws:

Throws an error if index is outside array bounds.

Type
Error
Returns:

Returns the numeric index.

Type
number

getDataByUVW(u, v, w)

Retrieves the linear index of the given cell in the data array.

This method addresses the 3D grid by fractional values in each axis. Each coordinate is given in the range 0 to 1, where zero means the minimum extent in each axis and one is the maximum extent.

Parameters:
Name Type Description
u number

The relative X-axis position of the cell (0 to 1).
v number

The relative Y-axis position of the cell (0 to 1).
w number

The relative Z-axis position of the cell (0 to 1).
Throws:

Throws an error if index is outside array bounds.

Type
Error
Returns:

Returns the numeric index.

Type
number

getDataIndex(i, j, k)

Retrieves the linear index of the given cell in the data array.

This method addresses the 3D grid by numerical index in each axis. Each coordinate is given as the index of the cell in that particular axis. An error is thrown if any index is less than zero or greater than the number of cells in that axis.

Whilst cells are arranged in 3 dimensions, the actual data for each cell is stored in a single flat array. Use this method to relate 3D model coordinates to a cell's index in the data array.

Parameters:
Name Type Description
i number

The X-axis index of the cell.
j number

The Y-axis index of the cell.
k number

The Z-axis index of the cell.
Throws:

Throws an error if index is outside array bounds.

Type
Error
Returns:

Returns the numeric index.

Type
number

getDataIndexByPos(x, y, z)

Retrieves the linear index of the given cell in the data array.

This method addresses the 3D grid by actual spatial position. Coordinates are given as an absolute position in space. An error is thrown if the position is outside the spatial extents of the grid.

Whilst cells are arranged in 3 dimensions, the actual data for each cell is stored in a single flat array. Use this method to relate actual model coordinates within a grid to a cell's index in the data array.

Parameters:
Name Type Description
x number

The X-axis position of the cell.
y number

The Y-axis position of the cell.
z number

The Z-axis position of the cell.
Throws:

Throws an error if index is outside array bounds.

Type
Error
Returns:

Returns the numeric index.

Type
number

getDataIndexByPosArray(pos)

Retrieves the linear index of the given cell in the data array.

This method addresses the 3D grid by actual spatial position. Coordinates are given as an absolute position in space. An error is thrown if the position is outside the spatial extents of the grid.

Whilst cells are arranged in 3 dimensions, the actual data for each cell is stored in a single flat array. Use this method to relate actual model coordinates within a grid to a cell's index in the data array.

Parameters:
Name Type Description
pos Array.<number>

An [x,y,z] coordinate position within the volume.
Throws:

Throws an error if index is outside array bounds.

Type
Error
Returns:

Returns the numeric index.

Type
number

getDataIndexByUVW(u, v, w)

Retrieves the linear index of the given cell in the data array.

This method addresses the 3D grid by fractional values in each axis. Each coordinate is given in the range 0 to 1, where zero means the minimum extent in each axis and one is the maximum extent.

Whilst cells are arranged in 3 dimensions, the actual data for each cell is stored in a single flat array. Use this method to relate unified relative grid coordinates to a cell's index in the data array.

Parameters:
Name Type Description
u number

The relative X-axis position of the cell (0 to 1).
v number

The relative Y-axis position of the cell (0 to 1).
w number

The relative Z-axis position of the cell (0 to 1).
Throws:

Throws an error if index is outside array bounds.

Type
Error
Returns:

Returns the numeric index.

Type
number

getIsoSurface( [threshold] [, shape])

Extracts a triangulated iso-surface at the given threshold using MarchingCubes and adds it to the given or a new shape.

Parameters:
Name Type Argument Description
threshold number <optional>

The value at which to generate the iso-surface, defaults to PD.VolumeArray#threshold.
shape PD.Shape <optional>

The shape to add to, defaults to a new shape if not defined.
Returns:

Returns shape or a new shape with the new iso-surface.

Type
PD.Shape

getSurface( [type] [, threshold] [, shape])

Extract a surface from the volumetric grid and add it to a given or new shape.

The type of surface created depends on the type parameter, where:

  • 0: Triangulated iso-surface (MarchingCubes),
  • 1: Polygonal iso-surface (SurfaceNet), and
  • 2: Voxelised surface.
Parameters:
Name Type Argument Description
type number <optional>

The type of surface (0:Triangular[MarchingCubes], 1:Polygonal[SurfaceNets], 2:Voxelised), defaults to 0.
threshold number <optional>

The value at which to generate the iso-surface, defaults to PD.VolumeArray#threshold.
shape PD.Shape <optional>

The shape to add the surfaces to, defaults to a new shape if not defined.
Returns:

Returns shape or a new shape with the new iso-surface.

Type
PD.Shape

getSurfaceNets( [threshold] [, shape])

Extracts a polygonal surface at the given threshold using SurfaceNets and adds it to the given or a new shape.

Parameters:
Name Type Argument Description
threshold number <optional>

The value at which to generate the iso-surface, defaults to PD.VolumeArray#threshold.
shape PD.Shape <optional>

The shape to add to, defaults to a new shape if not defined.
Returns:

Returns shape or a new shape with the new surface.

Type
PD.Shape

getVoxels( [threshold] [, shape])

Extract a voxelised surface at the given threshold using adds it to the given or a new shape.

Parameters:
Name Type Argument Description
threshold number <optional>

The value at which to generate the voxels, defaults to PD.VolumeArray#threshold.
shape PD.Shape <optional>

The shape to add to, defaults to a new shape if not defined.
Returns:

Returns shape or a new shape with the new surface.

Type
PD.Shape

interpolateDataByPos(x, y, z)

Retrieves the tri-linearly interpolated value at the given position.

If the point is outside the grid extents, this method returns zero.

Parameters:
Name Type Description
x number

The X-axis position of the cell.
y number

The Y-axis position of the cell.
z number

The Z-axis position of the cell.
Returns:

Returns the interpolated value, or zero.

Type
number

map(callback)

Applies the given function to each cell in the grid.

In this method, the 3D grid is addressed by the numerical index of the cell in each axis.

The callback is invoked with the following four (4) arguments and must return the value it wants stored for that grid cell:

  • i: The X-axis index of the cell.
  • j: The Y-axis index of the cell.
  • k: The Z-axis index of the cell.
  • index: The index of the cell in the data array.
Parameters:
Name Type Description
callback function

The function to be invoked for each cell.
Throws:

  • Error Throws an error if callback is not a valid function.

  • Throws an error if callback is not a valid function.

    Type
    Error
Returns:

Returns this grid instance to support method chaining.

Type
PD.VolumeArray

mapByPos(callback)

Applies the given function to each cell in the grid.

In this method, the 3D grid is addressed by actual spatial position. Each coordinate in the callback is given as the absolute position of the center of each cell in 3D space.

The callback is invoked with the following four (4) arguments and must return the value it wants stored for that grid cell:

  • x: The global Cartesian X-axis position of the cell.
  • y: The global Cartesian Y-axis position of the cell.
  • z: The global Cartesian Z-axis position of the cell.
  • index: The index of the cell in the data array.
Parameters:
Name Type Description
callback function

The function to be invoked for each cell.
Throws:

Throws an error if callback is not a valid function.

Type
Error
Returns:

Returns this grid instance to support method chaining.

Type
PD.VolumeArray

mapByUVW(callback)

Applies the given function to each cell in the grid.

In this method, the 3D grid is addressed by fractional values in each axis. Each coordinate in the callback is given in the range 0 to 1, where zero means the minimum extent in each axis and one is the maximum extent.

The callback is invoked with the following four (4) arguments and must return the value it wants stored for that grid cell:

  • u: The fractional X-axis position of the cell (0 to 1).
  • v: The fractional Y-axis position of the cell (0 to 1).
  • w: The fractional Z-axis position of the cell (0 to 1).
  • index: The index of the cell in the data array.
Parameters:
Name Type Description
callback function

The function to be invoked for each cell.
Throws:

Throws an error if callback is not a valid function.

Type
Error
Returns:

Returns this grid instance to support method chaining.

Type
PD.VolumeArray

setExtents(min, max [, expansion])

Sets the spatial extents of the 3D grid.

Parameters:
Name Type Argument Description
min Array.<number>

The [x,y,z] coordinate array of the minimum in each axis.
max Array.<number>

The [x,y,z] coordinate array of the maximum in each axis.
expansion number <optional>

A fraction of the cell size to expand extents by (0 to 1), defaults to 0.
Returns:

Returns this grid instance to support method chaining.

Type
PD.VolumeArray

setSize( [cells] [, min] [, max] [, expansion])

Sets the number of cells in the 3D grid and initialises data array.

Parameters:
Name Type Argument Description
cells Array.<number> <optional>

The [x,y,z] integer array giving the number of data cells in each axis.
min Array.<number> <optional>

The [x,y,z] coordinate array of the minimum in each axis.
max Array.<number> <optional>

The [x,y,z] coordinate array of the maximum in each axis.
expansion number <optional>

A fraction of the cell size to expand extents by (0 to 1), defaults to 0.
Returns:

Returns this volume instance to support method chaining.

Type
PD.VolumeArray

toJSON()

Used by JSON.stringify to convert a complex object to a POJO.

Returns:

Returns a simpler POJO version of this object for JSON formatting.

Type
object

toString_CSV()

Retrieves a comma-separated value (CSV) string containing volumetric data.

Returns:

Returns a formatted string containing volumetric data.

Type
string

toString_JSON( [indent])

Retrieves a JSON formatted string containing grid data.

NOTE: toJSON() is different as it returns an object rather than a string, and determines how the volume is converted to JSON.

Parameters:
Name Type Argument Description
indent string | number <optional>

An optional indent string, typically one or more spaces or tabs, or the number of spaces.
Returns:

Returns a JSON formatted string containing volumetric grid data.

Type
string

toString_VOX()

Retrieves a string containing voxel information data.

Returns:

Returns a formatted text string containing volumetric data.

Type
string