🌀 Working with Voxels

Shows all v-layers.

Layers creation

3DCoat allows to create multiple layers in the scene. And each layer can contain another layers.

Here's the code:

void main() {

    // prepare scene
    Vox  v;
    v.clearScene();

    // build vox-layers tree
    v
      .appendToParent( "Head" )
      .appendToParent( "Body" )
        .append(         "Neck" )
        .appendToParent( "Left arm" )
        .appendToParent( "Right arm" )
        .appendToParent( "Heart" )
        .appendToParent( "Left leg" )
        .appendToParent( "Right leg" )

      // back to "Head" layer, switch it
      // to "Surface mode" and attach new one
      .to( "Head" ).toSurface()
        .append( "Eye" )
        .appendToParent( "Lamps" )
      // Noticed how last one were added?
      // Correct: `S`, not `V`.
    ;

    // delete first (empty) layer from scene
    v.firstForRoot().remove();
}

You'll get the tree:

Check it!)

Do you see the groups of methods? append(), appendToParent(), appendToRoot(), forEach(), forRootEach(), ... - self-explanatory titles: "parent", "root", "for each". Simply compare this code with result image, and you'll get everything :)

Are you familiar with JQuery? Then you'll easily understand how 3DCoat works with trees.

Consider that class Vox interacts with 3DCoat's UI, that's why Vox-methods select layers before they do anything with them.

Layers traversal

Lets add some to the code above.

There are two ways. First:

// access to a Vox tree
Vox v;


void main() {

    // build a tree
    // look `CreateVoxelTree.as`
    // ...

    // walk through all layers and for each layer call invert() function
    // look below `void invert()`
    v.forRootEach( "invert" );

    // move to "Body" layer and call `invert()` for it and its children
    v.to( "Body" ).call( "invert" ).forEach( "invert" );
}




// function for `forEach()`, look above
void invert() {

    v.isSurface() ? v.toVoxel() : v.toSurface();

    // pause, to see movement in the UI
    Wait( 50 );
}

Second:

// access to voxTree
Vox v;


void main() {

    // build a voxel layers tree
    // look `CreateVoxelTree.as`
    // ...

    // access by index for all children of "Head" layer
    v.to( "Body" ).call( "invert" );
    for ( int i = 0; i < v.count(); ++i ) {
        v.at( i ).call( "invert" ).parent();
        Wait( 100 );
    }
}




// look above for function `forEach()`
void invert() {
    v.isSurface() ? v.toVoxel() : v.toSurface();
}

Which way to choose? You decide.

The building of vox-layers tree see here

Layers methods (surface and voxel mode)

Vox& moveToIndex(const string& name, int index);

Move v-layer name as child of parent's selected v-layer into the relative index . V-layer becomes selected.

Vox v;
// Select the child "Lamps" of parent v-layer "Head" (index = 1) 
v.moveToIndex("Head",1);

Vox& moveCurrentToIndex(int idx);

Move the current v-layer as child of parent's selected v-layer into the relative index. v-layer with index equals to idx becomes selected

Parameters

idx	v-layer index

//Examples:
Vox v;
// Select the child "Eye" of parent v-layer "Head" (index = 0) 
v.moveToIndex("Head",0);
    
// Move the the child layer "Eye" into layer "Lamps" with relative index equals to 1. 
v.moveCurrentToIndex(1);

int getIndex();

Gets the index of current v-layer

string names();

Gets all volumes for brunch.

string namesQuotes();

Gets all volumes for brunch (comma separated).

//Examples:
Debug      dbg;
DebugLog   log = dbg.log();
const string  s = v.names();
log += s;
const string  sq = v.namesQuotes();
log += sq;

string name();

Gets the current volume name.

Vox& rename(const string& newName);

Rename the current volume.

Parameters

newName

name to rename

Vox& to(const string& name);

Switch to v-layer named like name.

Parameters

name	new layer name

//Examples:
Vox v;
v.rename( "My head" );
v.to( "My head" );

Vox& parent();

Selected a parent if parent isn't root. #! We can't selecting a root's v-layer (don't selecting really in the 3D-Coat UI). Use appendToParent() for add a new v-layer to root.

Don't moves to the root's v-layer.

bool hasParent();

Check if volume layer has parent

Returns

TRUE when selected v-layer have a not root's parent.

Vox& firstForRoot();

Move to a first v-layer among childs of root's v-layer.

Vox& first();

Move to a first v-layer among childs of selected v-layer.

Vox& firstForParent();

Move to a first v-layer among childs of parent's selected v-layer.

Vox& nextForParent();

Move to a next v-layer among childs of parent's selected v-layer. Stops when parent is last.

bool hasChildren();

Check the children layers for current volume.

Returns

TRUE when selected v-layer consist of other v-layers.

bool hasNextForParent();

Check the next layer for parent volume.

Returns

TRUE when has a next v-layer for childs of parent's selected v-layer.

bool next();

Select the next volume. Move through all v-layers ignoring depths.

Vox& lastForRoot();

Move to a last v-layer among childs of root's v-layer.

Vox& last();

Move to a last v-layer among childs of selected v-layer.

Vox& lastForParent();

Move to a last v-layer among childs of parent's selected v-layer.

Vox& remove();

Remove the current v-layer from vox branch tree.

Vox& forRootEach(const string& func);

Move through all v-layers and run func for every.

Vox& forEach(const string& func);

Move through all parents v-layers (relative selected) and run func for every.

Vox& call(const string& func);

Run func for selected v-layer

Vox& atForRoot(int i);

Select a child of root's v-layer by index.

Vox& at(int i);

Select a child of current v-layer by index.

Vox& atForParent(int i);

Select a child of parent for current v-layer by index.

Vox& showAllHidden();

Vox& showHiddenSubtree();

Shows hidden subtree v-layers for current vox tree branch.

Volume object methods

Mat4 transform();

Gets the transform matrix from current volume object.

Vox& setTransform(const Mat4& m);

Sets the transform matrix for the current volume object.

bool visible();

Gets the visibility of the current volume object.

Vox& setVisible(bool v);

Sets the visibility of the current volume object.

bool ghost();

Gets the ghost mode of the current volume object.

Vox& setGhost(bool v);

Sets on/off the ghost mode of the current volume object.

string nameShader();

Gets the shader name of the current volume object.

Vox& setShaderProperty(const string& name, const string& vs);

Sets the shader property of the current volume object.

Parameters

name	property id
vs	string value

Vox& setOpacity(float v);

Sets the opacity for current volume object.

Parameters

v	opacity value

Vox& setColor(int v);

Sets the color for current volume object.

Parameters

v	color 32-bits(argb) value

Vox& setColorRGB(int r, int g, int b);

Sets the RGB color for current volume object.

Parameters

r	red channel
g	green channel
b	blue channel

Vox& toSurface();

Sets the current volume to surface mode.

Vox& toVoxel();

Sets the current volume to voxel mode.

Vox& toVoxelSuggestPoly(int suggestPoly);

Sets the current volume to voxel mode with corresponding number of polygons.

Parameters

suggestPoly

polygon count.

Vox& decreaseObject2X();

Decreminate the dencity of volume object's by 2 times

Vox& increaseObject2X();

Increminate dencity of volume object's by 2 times.

Vox& toGlobalSpace();

Sets the volume objects to the global space.

Vox& toUniformSpace();

Sets the volume objects to the uniform space.

Vox& resample();

Change resolution of the volume object.

Vox& applyAxialSymmetry();

Sets the radially array the object with any number of slices.

Vox& extrude();

Extrude the volume object.

Vox& turnToShell();

Thickens the surface of volume object. Only for surface mode.

Vox& makeVoxelHull();

Make a shell mesh using the voxel algorithm. It takes more time to calculate but works well for complex topology. Only for voxel mode.

Vox& makeSurfaceHull();

Thickens the mesh object using surface extrusion. Only for surface mode.

Vox& closeSurfaceHoles();

Close the surface holes in mesh. Only for surface mode.

Vox& fillVoids();

Fills inner voids or hollows in the model. Only for voxel mode.

Vox& closeInvisibleHulls();

Close invisible hulls inside the object. Even if hull is not completely closed it may be closed by this tool because only small outer part of the hull is visible. Only for voxel mode.

Vox& decompose();

Creates an object in the VoxTree for each separated piece of geometry, and places the geometry into those objects. Only for surface mode.

Vox& save3B();

Save Volume as 3B.

Vox& saveSubtree3B();

Save Volume w/ Sub-Tree as 3B.

Vox& merge3B();

Import external 3B file in scene.

Vox& mergeCloud();

Import set of points as a sequence of small spheres.

Vox& mergeObject();

Import 3D object.

Vox& exportScene();

Export entire scene as a multi-object file.

Vox& exportObject();

Export current object to a file on disk.

Vox& exportPatternForMerge();

Export current object to be used as a preset in the Meshes panel.

Vox& exportCurveProfile();

Export current object to be used as a preset in the Meshes panel.

Vox& autopoQuadrangulate();

Run AUTOPO and switch to Retopo room.

Vox& autopoQuadrangulateAndMergePtex();

Run AUTOPO and bake using PTEX technology.

Vox& autopoQuadrangulateAndMerge();

Run AUTOPO to begin texturing in Paint room.

Vox& autopoQuadrangulateAndMergeDP();

AUTOPO for Per Pixel.

Vox& putOnGround();

Snap object to ground (zero). Only vertical parallel motion will be used.

Vox& layOnGround();

Lay object on ground. Object will be moved and rotated to get physically stable position on the ground.

Vox& cloneInstance();

Clone instances.

Vox& clone();

Clone and transform volume object.

Vox& cloneInstanceWithSymmetry();

Clone instances with symmetry.

Vox& cloneSymmetry();

Clone with symmetry and transform.

Vox& cloneDegrade();

Clone and decrease level of details twice.

Vox& cloneSpace();

Create space with identical density and transformation. It is important if you want to use copy tool without losing quality. Create new space and use copy tool.

Vox& flipX();

Flip object along X.

Vox& flipY();

Flip object along Y.

Vox& flipZ();

Flip object along Z.

Vox& flipNormals();

Flip object normals. Only for surface mode.

Vox& bakeColors();

Bake color from all visible volumes to the current one. The volume will turn to surface mode.

Vox& plainMergeVisible();

Merge Visible (no booleans)

Vox& plainMergeSubtree();

Merge Sub-Tree (no booleans).

Vox& plainMergeTo(const string& with);

Copy & Merge (no booleans).

Vox& plainMoveTo(const string& with);

Merge (move, no booleans).

Vox& mergeVisible();

Combine current layer with all child layers.

Vox& mergeSubtree();

Merge the Sub-Tree of current volume. All child layers will be deleted.

Vox& mergeTo(const string& with);

Merge copy of the object to other object.

Parameters

with	name of the destination volume

Vox& moveTo(const string& with);

Move object to other object space.

Parameters

with	name of the destination object

Vox& subtractFrom(const string& with);

Subtract object from other object.

Parameters

with	name of the object to subtract from

Vox& intersectWith(const string& with);

Intersect volume with other one.

Parameters

with	name of the object to intersect with

Vox& removeIntersectionWith(const string& with);

Subtract current volume from the destination but leave both volumes. In so way intersecting part will be removed from the destination object.

Parameters

with	name of the object to intersect with

Vox& splitWith(const string& with);

Split volume in two parts(volumes) with destination volume.

Parameters

with	name of the object to split with

Vox& changeParent(const string& with);

Change parent of the object.

Parameters

with	name of the object to change

void addObject(const string& name);

Add the sub object to poly mesh.

Parameters

name	sub object name

int objectIndex(const string& name);

Gets index of object by name ID.

Parameters

name	object name ID

Returns

object index

string objectName(int index);

Get the object name ID by index

Parameters

index

object index

Returns

object name

void renameObject(const string& oldName, const string& newName);

Rename the sub object.

Parameters

oldName	old object name
newName	new objejct name

bool visibleObject(const string& name);

Get the object visibility.

Parameters

name	object name

Returns

true if object is visiable otherwise false.

void setVisibleObject(const string& name, bool v);

Get the object visibility.

Parameters

name	object name
v	visibility flag

void lockObject(const string& name, bool b);

Set the lock mode for named object.

Parameters

name	object name
b	lock flag

int uvsetIndex(const string& name);

Gets the retopo UVsets index by name.

Parameters

name	retopo uvsets name

Returns

uvsets index.

string uvsetName(int index);

Gets the retopo uvsets name by index.

Parameters

index

index value

Returns

uvset name

void renameUVSet(const string& oldName, const string& newName);

Rename the old uvset name by new name

Parameters

oldName	old name
newName	new name

bool isEmpty();

Checks whether a volume is empty.

Returns

true if the volume is empty, false otherwise.

bool isSurface();

Checks whether a current volume mode is surface.

Returns

true if the current volume mode is surface, false otherwise.

bool isVoxel();

Checks whether a current volume mode is voxel.

Returns

true if the current volume mode is voxel, false otherwise.

Paint Layers methods

void addPaintLayer(const string& name);

Add the paint layer.

Parameters

name	layer's name

void deletePaintLayers();

Delete the current paint layer.

string paintLayer();

Gets the current layer name.

Returns

string name

bool setPaintLayer(const string& name);

Select the paint layer.

Parameters

name	layer's name

void renamePaintLayer(const string& newName);

Rename the current paint layer.

Parameters

newName

layer's name

void firstPaintLayer();

Select the first paint layer.

bool nextPaintLayer();

Select the next paint layer.

bool visiblePaintLayer();

Gets the visibility of the current paint layer.

Returns

true if paint layer is visiable otherwize false.

void setVisiblePaintLayer(bool v);

Gets the visibility mode of the current paint layer.

Parameters

v	visible value

float opacityPaintLayer();

Gets the opacity of the current paint layer.

Returns

opacity

void setOpacityPaintLayer(float v);

Sets the opacity of the current paint layer.

Parameters

v	opacity value(0..1)

float depthOpacityPaintLayer();

Gets the depth opacity of the current paint layer.

Returns

depth opacity

void setDepthOpacityPaintLayer(float v);

Sets the depth opacity of the current paint layer.

Parameters

v	opacity value(0..1)

void setBlendingPaintLayer(const string& name);

Set blending mode of the current paint layer.

Parameters

name	id's of the color blending mode

void setDepthBlendingPaintLayer(const string& name);

Sets depth blending mode of the current paint layer.

Parameters

name	id's of the depth blending mode

Retopo Layers methods

void deleteRetopoLayer();

Delete the current retopo layer.

string retopoLayer();

Gets the current retopo layer.

Returns

layer name

bool setRetopoLayer(const string& name);

Select retopo layer with name ID.

Parameters

name	id of layer name

Returns

false if layer not found.

void renameRetopoLayer(const string& newName);

Rename the current retopo layer.

Parameters

newName

name to rename

void firstRetopoLayer();

Select first retopo layer.

bool nextRetopoLayer();

Select next retopo layer.

Returns

false if current layer is last and no new layer was selected.

bool visibleRetopoLayer();

Gets visibility of the current retopo layer.

Returns

visibility mode.

void setVisibleRetopoLayer(bool v);

Set visibility of current retopo layer.

Parameters

v	visibility mode.

Materials methods

void addMaterial(const string& name);

Add the material to poly mesh materials.

Parameters

name	material name

void deleteMaterial(const string& name);

Delete the material from poly mesh materials.

Parameters

name	material to delete

int materialIndex(const string& name);

Gets the material index by name.

Parameters

name	material name

Returns

material index

string materialName(int index);

Gets the material name by index.

Parameters

index

material index

Returns

material name

void renameMaterial(const string& oldName, const string& newName);

Rename the old material name on the new name.

Parameters

oldName	old name
newName	new name

bool visibleMaterial(const string& name);

Gets the visibility of material.

Parameters

name	material name

Returns

true if material is visiable, otherwise false.

void setVisibleMaterial(const string& name, bool v);

Sets the visibility of material.

Parameters

name	material name
v	visibility

void lockMaterial(const string& name, bool b);

Set the lock mode of the material.

Parameters

name	material name
b	locked flag (true/false)

Scene methods

Vox& clearScene();

Clear a scene.

int count();

Calculate of child object's count for current voxel tree branch.

Returns

Number of child objects

float square();

Gets a current volume square.

Returns

square value

float volume();

Gets a volume of the current volume.

Returns

volume value

int polycount();

Gets the number of polygons of the current volume.

Returns

polygons count

int polycountScene();

Gets polygons count of scene volumes

Returns

polygons count

int countPaintLayer();

Gets a layers count of the poly mesh.

Returns

layers count

int countRetopoLayer();

Gets amount of retopo layers.

Returns

number of retopo layers

int countMaterial();

Gets amount of poly mesh materials.

Returns

numbers of materials

int countObject();

Gets amount of poly mesh objects.

Returns

numbers of objects.

int countUVSet();

Gets amount of uvsets.

Returns

number of uvsets.

Functions

If you prefer a functional programming, take a look at this list of available functions:

// Returns true if current volume is in surface mode.
DEPRECATED bool IsSurface();

// Check if volume cached.
DEPRECATED bool IsInCache();

// Move current volume to cache.
DEPRECATED void ToCache();

// Restore current volume from cache.
DEPRECATED void FromCache();

// Get current volume name.
DEPRECATED string GetCurVolume();

// Rename current volume.
DEPRECATED void RenameCurVolume(string &name);

// Set surface/voxel mode for volume Surf=true - set surface mode,
// false - volume. It is same as click on S/V icon.
// If silent=true then no dialogs will be shown, all will be
// done by default.
DEPRECATED void SetCurVolumeMode(bool Surf,bool Silent);

// Set current volume by name, returns true if succeed.
DEPRECATED bool SetCurVolume(string &name);

// Select first volume in scene, if OnlyVisible==true then first
// visible volume will be selected.
DEPRECATED void SelectFirstVolume(bool OnlyVisible);

// Select next volume after current in tree, if OnlyVisible==true
// then next visible volume will be selected. Returns false if
// current volume is last in list.
DEPRECATED bool SelectNextVolume(bool OnlyVisible);
// Example of walking through all volumes:
    void main() {
        string s=GetCurVolume(); //keep current selection
        SelectFirstVolume(true);
        do {
            //insert your action
        } while( SelectNextVolume(true));
        SetCurVolume(s); //restore initial selection
    }

// Checks if volume is empty.
DEPRECATED bool CurVolumeIsEmpty();

// Get current volume polycount.
DEPRECATED int GetCurVolumePolycount();

// Get polycount of whole voxel scene.
DEPRECATED int GetVoxSceneVisiblePolycount();

// Get polycount of visible volumes.
DEPRECATED int GetVoxScenePolycount ();

// Get current volume shader name.
DEPRECATED string GetCurVolumeShader();

// Set volume visibility (like with eye icon).
DEPRECATED void SetVolumeVisibility(bool vis)

// Returns current volume visibility.
DEPRECATED bool GetVolumeVisibility()

// Sets Ghost property to volume.
DEPRECATED void SetVolumeGhosting(bool Ghosting)

DEPRECATED void SetCurVolumeTransform(Mat4& transform)

// Set/get current volume transform as 4-dimentional matrix.
// See the Mat4 class description.
DEPRECATED Mat4 SetCurVolumeTransform()

DEPRECATED bool GetVolumeSquare()

// Get square and volume of the current volume.
DEPRECATED bool GetVolumeVolume()

// Get Ghost property from the volume.
DEPRECATED bool GetVolumeGhosting()

// Set opacity of the current volume if the shader
// has corresponding property.
DEPRECATED void SetVolumeOpacity(float Opacity)

// Set current volume color if this property of shader is available.
DEPRECATED void SetVolumeColor(int Color)

// Assign val to current object shader property field.
DEPRECATED void SetShaderProperty(string &id, string &val)

Also check this full list of functions:

// Returns whole command line.
string getCommandLine();

// Stores some string as global value that may be read later in
// the session. The value will be stored in 3B file and you will
// be able to read in further work with this scene. 
DEPRECATED void SetGlobalVar(string& Name,string& Value)

// Returns value previously stored using SetGlobalVar.
DEPRECATED string GetGlobalVar (string& Name)

// Returns scene filename (last saved or opened as 3B file).
DEPRECATED string GetSceneFileName()

// Sets scene filename for further saving.
DEPRECATED void SetSceneFileName(string& Name) 

// Highlight element with red rectangle.
// Pass the `time` in seconds.
void HighlightUIElement(string &ID, float time);

// Goes to one of previous dialogs in call stack.
DEPRECATED void back(int steps=1);

// Opens window described by xml-file pointed by Path.
// If Path contains .3b file will be opened as 3B file.
DEPRECATED void open(string &Path);

// Opens model for PPP, if path is empty, shows open dialog.
DEPRECATED void ppp(string &path);

// Opens model for MV painting, if path is empty, shows open dialog.
DEPRECATED void mv(string &path);

// Opens model for Ptex, if path is empty, shows open dialog.
DEPRECATED void ptex(string &path);

// Import image as mesh, dialog will be shown.
DEPRECATED void imagemesh();

// Import mesh as reference, if path is empty dialog will be shown.
DEPRECATED void refmesh(string &path);

// Import mesh for vertex painting, if path is empty dialog will be shown.
DEPRECATED void vertexpaint(string &path);

// Perform autopo over the mesh chosen in dialog.
DEPRECATED void autopo(string &path);

// Opens mesh for repairing. If id contains "vox" then model will be
// voxelized, if there is substring "shell" then mesh will be imported
// as thin shell. Mesh Opening dialog will be shown.
DEPRECATED void repair(string &id);

// Activate bas-relief tool.
DEPRECATED void bass();

// Activale remove undercuts mode.
DEPRECATED void undercut();

// Activate special voxel tool. id may be found in English.xml between
// <ID>...</ID> if you will find name of tool between
// <Text>...</Text> tags.
DEPRECATED void activate(string &id);

// Activate retopo tool.
DEPRECATED void retopo();

// Open mesh using dialog and merge as retopo mesh.
DEPRECATED void retopopen();

// Activate any room - name is one of "Paint", "Tweak", "UV",
// "Voxels", "Retopo", "Render".
DEPRECATED void ToRoom(string &name);

// Check if you are in specified room - name is one of "Paint",
// "Tweak", "UV", "Voxels", "Retopo", "Render".
DEPRECATED bool IsInRoom(string &name);

// Add new volume in voxel room. If name is empty name will be
// assigned automatically.
DEPRECATED void AddNewVolume(string &name);

// Activate UV room.
DEPRECATED void uv();

// Activate voxel room and add new volume.
DEPRECATED void vox();

// Create sphere of radius R in voxel room in current object.
// \param mode 0 - add, 1 - subtract, 2 - intersect with scene.
DEPRECATED void sphere(float x,float y,float z,float r,int mode);

// Create cube in voxel room in current object.
// \param mode 0 - add, 1 - subtract, 2 - intersect with scene.
// \param sizex Size by X-axis.
// \param sizey Size by Y-axis.
// \param sizez Size by Z-axis.
DEPRECATED void cube(float x,float y,float z,float sizex,float sizey,float sizez,int mode);

// Turn all volumes to surface mode.
DEPRECATED void surf();

// Turn current volume to the surface mode.
DEPRECATED void cursurf();

// Turn current volume to voxel mode, voxelize if need.
DEPRECATED void voxelize();

// Sets merging options in voxel room. opt is just set of substrings
// with different options. Possible values are:
// [voxelize=true]
// [voxelize=false]
// [separate=true]
// [separate=false]
// [respectneg=true]
// [respectneg=false]
// [as_skin=true]
// [as_skin=false]
// [skin=....] - to set skin thickness.
DEPRECATED void mergeopt(string &opt);
// Example:
mergeopt( "[voxelize=true][as_skin=true][skin=4.5]" );

// Merge model in voxel room. Empty string means that dialog will be shown.
DEPRECATED void merge(string &model);

// Activate voxel primitives tool. Possible primitives:
// cube, cylinder, sphere, tube, cone, ellipse, n-gon, gear.
DEPRECATED void prim(string &id);

// Apply in current tool (same as press enter).
DEPRECATED void apply();

// Apply in Merge tool without asking "Keep scale?".
// Scale will not be kept and scene scale will not be changed.
DEPRECATED void ApplyAndKeepScale();

// Apply in current tool (same as press enter) wint one difference -
// in Merge tool scale of merged object sill be automatically kept and
// scene scale changed if this merge is first.
DEPRECATED void mapply();

// Open recent 3B-file.
DEPRECATED void recent3b();

// Print text to MyDocuments/3D-CoatV4/log.txt.
DEPRECATED void Log(string &line);

// Generate integer random number min..max.
int rand(int min,int max);

// Generate floating random number min..max.
float randF(float min,float max);

// Set random generator seed.
void seed(int val);

// Show progress bar pos = 0..100.
DEPRECATED void ProgressBar(const string& message,int pos);

// Set orthogonal (true) or perspective (false) view mode.
DEPRECATED void SetOrthoMode(bool value);