voctopus.core - nphyx/voctopus GitHub Wiki

core

Description

Voctopus Core

This contains the core Voctopus object.

Quick definition of terms:

  • 1 octant = one voxel at a given depth
  • 1 octet = 8 octants, or one tree node

Members:

  • octantSize
  • startSize

#Functions


Voctopus

Voctopus(depth, schema) ⇨ Voctopus

The Voctopus constructor. Accepts a maximum depth value and a schema (see the schemas module for more info).

Parameters

name type description
depth int maximum depth of tree
schema Array data

Returns: Voctopus


expand

expand() ⇨ bool

Expands the internal storage buffer. This is a VERY EXPENSIVE OPERATION and should be avoided until neccessary.

Returns: booltrue if the voctopus was expanded, otherwise false


get

get(index, out) ⇨ voxel

Gets the properties of an octant at the specified index. If the index is invalid you'll get back garbage data, so use with care.

Example:

let voc = new Voctopus(5);
let index = voc.init([9,3,2]); // initializes the voxel at 9,3,2 and returns its index 
voc.get(index); // {r:0,g:0,b:0,m:0}

Parameters

name type description
index int index to set
out voxel out param (defaults to instance of this.voxel)

Returns: voxel


set

set(p, r, g, b, a) ⇨ undefined

Sets the properties of an octant at the specified index. Be careful with using it directly. If the index is off it will corrupt the octree.

Example:

let voc = new Voctopus(5);
let index = voc.init([9,3,2]); // initializes the voxel at 9,3,2 and returns its index 
voc.set(index, 232, 19, 224, 63); // r = 232, g = 19, b = 224, a = 64 

Parameters

name type description
p int index to write to
r int red channel
g int green channel
b int blue channel
a int alpha channel

Returns: undefined


init

init(v, depth) ⇨ int

Initializes a voxel at the supplied vector and branch depth, walking down the tree and allocating voxels at each level until it hits the end.

Example:

let voc = new Voctopus(5);
voc.init([9,3,2]); // 1536 (index)

Parameters

name type description
v vector coordinate vector of the target voxel
depth int depth to initialize at (default max depth)

Returns: intindex


walk

walk(v, depth, p) ⇨ array

Walks the octree from the root to the supplied position vector, building an array of indices of each octet as it goes, then returns the array. Optionally initializes octets when init = true.

Example:

let voc = new Voctopus(5);

Parameters

name type description
v vector coordinate vector of the target voxel
depth int number of depth levels to walk through (default this.depth)
p int start pointer (defaults to start of root octet)

Returns: arrayindexes of octant at each branch


getVoxel

getVoxel(v, out, d) ⇨ voxel

Gets the properties of a voxel at a given coordinate and (optional) depth.

Example:

var voc = new Voctopus(5, schemas.RGBM);
voc.getVoxel([13,22,1], 4); // {r:0,g:0,b:0,m:0} (index)

Parameters

name type description
v vector [x,y,z] position
out voxel out param (defaults to instance of this.voxel)
d depth max depth to read from (default max depth)

Returns: voxel


setVoxel

setVoxel(v, props, d) ⇨ index

Sets the properties of an octant at a given coordinate and (optional) depth.

Example:

var voc = new Voctopus(5, schemas.RGBM);
voc.setVoxel([13,22,1], {r:122,g:187,b:1234,m:7}, 4); // 1536 (index)

Parameters

name type description
v vector [x,y,z] position
props object a property object, members corresponding to the schema
d depth depth to write at (default max depth)

Returns: indexpointer to the voxel that was set


seek

seek(v, depth) ⇨ int

Steps through the tree until it finds the deepest voxel at the given coordinate, up to the given depth.

Parameters

name type description
v vector coordinate vector of the target voxel
depth int depth to initialize at (default this.depth - 1)

Returns: intindex


setOctet

setOctet(v, data, d) ⇨ undefined

Sets the data for each element in an octet. Pointers are managed automatically. This can be a big performance boost when you have multiple voxels to write to the same octet, since it avoids redundant traversal. Octet location is automatically derived from the given vector so it doesn't have to point at the first voxel in the octet. If the octet doesn't currently exist in the tree it will be initialized.

Example:

let voc = new Voctopus(6);
let data = array[
	 {}, // members may be empty, but must be present so the indexes are correct
	 {r:210,g:12,b:14,a:15}, // can use all properties
	 {a:7},   // or
	 {g:82},  // any
	 {b:36},  // combination
	 {r:255}, // thereof
	 {},
	 {}
];
// in this example, walk to the second-lowest depth to find the pointer
voc.set.octet([0,0,1], data); // and done!

Parameters

name type description
v vector position vector for target octet
data array data to write, as an array of 8 objects (see example)
d depth depth to write at (default max depth)

Returns: undefined


getOctet

getOctet(v, out, d) ⇨ array

Gets an array of each voxel in an octet. Pointers are managed automatically. This can be a big performance boost when you have multiple voxels to write to the same octet, since it avoids redundant traversal. Octet location is automatically derived from the given vector so it doesn't have to point at the first voxel in the octet. If the octet doesn't currently exist in the tree it will be initialized.

Example:

let voc = new Voctopus(5, schemas.I8M16P);
voc.getOctet([0,0,0], 3)
	.map((voxel) => console.log(voxel)); // {m:0} (x8)

Parameters

name type description
v vector coordinates of voxel
out octet (optional) a collection of 8 voxels to store output
d depth (optional, default max depth) depth to write at

Returns: arrayarray of 8 voxels ordered by identity (@see voctopus/util#octetIdentity)