The SVX format(Simple Voxels) is a voxel transmital format. It was developed to enable the upload of voxel based models to Shapeways. The design priorities are simple definition, ease of implementation, and extensibility.
The basic format is a Zip file, named with a .svx extension. It contains a manifest file and a series of slices as images.
Here is a simple sphere encoded as an SVX file: Example
The archive contains an XML formatted file, named manifest.xml, placed in the top level directory. This file contains all non image data about the voxel grid.
An example manifest file:
<?xml version="1.0"?> <grid version="1.0" gridSizeX="256" gridSizeY="256" gridSizeZ="256" voxelSize="0.0001" subvoxelBits="8" slicesOrientation="Y" > <channels> <channel type="DENSITY" bits="8" slices="density/slice%04d.png" /> </channels> <materials> <material id="1" urn="urn:shapeways:materials/1" /> </materials> <metadata> <entry key="author" value="Alan Hudson" /> <entry key="creationDate" value="2014/09/12" /> </metadata> </grid>
The <grid> element defines the main properties of the grid. The defined XML attributes are:
- version – The specification version this file follows, defaults to 1.0.
- gridSizeX – The number of voxels in the x direction.
- gridSizeY – The number of voxels in the y direction.
- gridSizeZ – The number of voxels in the z direction.
- originX – The x origin of the grid in physical space in meters, default is 0.
- originY – The y origin of the grid in physical space in meters, default is 0.
- originZ – The z origin of the grid in physical space in meters, default is 0.
- slicesOrientation – The axis(X,Y,Z) orthogonal to the slices plane, default is Y.
- subvoxelBits – number of bits used per voxel for density (1-16), default is 8.
- voxelSize – The physical size of each voxel in meters.
When using the slicesOrientation attribute, the following mapping is used between voxel coordinates and pixel coordinates
- X = slice,i,j
- Y = i,slice,j
- Z = i,j,slice
The <channels> element defines what data is stored in the image files. It contains a list of channel elements.
A <channel> element is used to define each channel in the file. Each channel is stored in its own image stack. This allows the PNG lossless data compression to work and makes viewing the separate channels easy in an image editor. The define XML attributes are:
- type – The type of information stored in this channel.
- bits – The number of bits used for the channel, default is 8 bits.
- slices – The file pattern showing how the files are named. Follows the printf spec (for example “folder/slice%04d.png”). The first file index has to be 0, last file index(gridSizeN-1)where N – is X,Y,Z depending on orientation.
The following channel types are defined. In the future more types maybe added.
- DENSITY – each value represents an approximation to the percent of voxel fill. It is normalized such that 100% fill corresponds to subvoxelResolution = (1 << subvoxelBits – 1), the surface of the shape corresponds to density value (1 <<(bits-1) – 0.5. Density property has similarity with alpha channel in image processing. It can be used to generate shapes with significantly reduces stair stepping effect on the surfaces. However, it can not be used to create “semi transparent” object.
- COLOR – RGB per voxel combined into 1 map.
- MATERIAL(id) – Fraction of amount a given material used in a voxel (all densities must sum to 100% or 0%).
- CUSTOM(id) – Custom value without defined semantic meaning.
Any numbered field such as MATERIAL(id) or CUSTOM(id) can have an unbounded amount of values with a non continuous range.
The <materials> element defines how the MATERIAL(id) maps to real world materials. It contains a list of material elements.
A <material> element is used to define each material used in the file.
- id – The value stored in the channel.
- urn – The URN referencing the material.
The material(id) to material urn mapping allows an upload to specify exactly what material it wants. 3D printed materials are a combination of technology, color, finishing steps(polish)… so I’m not totally certain this maps. But it would be nice to have the material at least defaulted right. For now I expect each printer and service bureau will have it’s own separate namespaces.
The <metadata> element defines a file level metadata via a map. It contains a list of entry elements.
The contents of the metadata field is undefined and is for user level metadata specification. Readers and writers should preserve metadata information.
The <entry> element is used to define each mapping.
- key – The key.
- value – The value.
How to encode slices
The slices are defined using PNG images. Each image series contains one channel of information. The bit count per pixel should be large enough to store the channel bits. Using more bits if desired, Ie storing a 1 bit image in an 8 bit channel is acceptable if not optimal.
Currently we’re suggesting that palette color types not be used. This decision is under review but it does lower the implementation costs. What’s not certain is whether writers of PNG files always have control over this.
We are still working out what the correct license is for a specification document. For now we can clearly state we’ll provide continuing free access to this specification. Implementer’s will not be charged for access to the spec document. We make no claims about any Intellectual Property others may claim as necessary to implement this specification.
Shapeways Implementation Notes
Currently only DENSITY channels are read.
There are two metadata entries the Shapeways system uses as hints if it needs to generate triangles from the voxel data.
The meshErrorFactor which defaults to .1 is used in the following formula: err = ef * voxelSize * voxelSize. This determines the maximum error the decimator will allow for edge collapses. 0.1 is a good value.
The meshSmoothingWidth is a parameter for the smoothing kernel we run while creating triangles. We found running a smoothing helped the final quality. By default we smooth at half the voxel size(0.5). This is subjective and will vary by content type and intent. The triangle count will increase dramatically with lower values.