SVX Format

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

Manifest File
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" >

        <channel type="DENSITY" bits="8" slices="density/slice%04d.png" />

        <material id="1" urn="urn:shapeways:materials/1" />

        <entry key="author" value="Alan Hudson" />
        <entry key="creationDate" value="2014/09/12" />

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.

Specification License
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.

32 Responses to SVX Format

  1. Pingback: Shapeways Blog - Shapeways Launches SVX Voxel File Format for 3D Printing

  2. Pingback: Shapeways Launches SVX Voxel File Format for 3D Printing | 3D Printing Magazine

  3. Pingback: Shapeways Announces New Pricing Scheme, and Creates Voxel Based SVX File Format -

  4. Pingback: Shapeways Launches SVX a Voxel Based File Format for 3D Printing | Katrina Monarco

  5. Tom Beddard says:

    Very interested to see this finally. Will you be making any example files available so we can see what it is like in reality?

  6. Magic says:

    100% fill corresponds to subvoxelResolution = (1 << subvoxelBits) -1 I guess.
    1<<8 cannot be store on 8 bits 🙂
    So if I understand well, there is no interpolation between the images: 1 image = 1 layer of voxels.

  7. Pingback: IP and Distributed Manufacturing | Thoughts from Tom Kurke

  8. Andreas Gustafsson says:

    The description of the grid element fails to document the voxelSize attribute. It needs to at least say what units it is in.

  9. donbright says:


    Thanks for writing this.

    Can you tell me the license on the example files? Thanks very much

    don b

  10. Jon Parker says:

    What is the voxel-count dimension limit to geometry that Shapeways will accept?

    • Alan Hudson says:

      The servers are set to accept up to 2000 x 2000 x 2000 voxels. In addition the total triangle count must be < 2 million. Practically this means for most interesting geometry you'd need to keep is around 1000 ^3 max.

  11. Nikola Ivanovic says:

    is there a possibility to get some more information on general slicing algorithm and process “behind” the curtain? It is for scientific purposes – phd thesis. You can contact me on my email for further discussion.

    Thank you

  12. Is it possible to get more meaningful error messages? I’ve been tweaking my generated SVX file, and it starts processing for longer (presumably meaning I’m making fewer dumb mistakes), but always get the dreaded: “We’re unable to process this file. Check your file for errors and click ‘Update File’ to upload a new version.”

    I’ve already run into the 1-bit vs. 8-bit grayscale issue here: 🙂

    If you’re curious, my latest attempt is at:


    • Alan Hudson says:

      if you download abfab3d the you can run svxconv yourself in apps/svxconv. just change the ant run task to specify your file.

      This example is complaining that:

      [java] [Fatal Error] :3:33: Element type “grid” must be followed by either attribute specifications, “>” or “/>”.

      Add, your gridSizeZ attribute is missing a close quote.

      I think you have your y and z backwards. svx is y up

      Here is what I used to successfully parse it

      The total file is about 1.5M triangles and the top is not closed. Make sure to leave a blank voxel on the top and bottom. Likely we should be doing that but for now you need to insure there is blank space before the voxel grid stops.

      The surface finish is also a bit rough looking, that said looking at your images that’s true as well. you can use typical grayscale/antialiased values if you smoother surfaces.

      • cutelyaware says:

        Please do add the blank padding to the code. It’s hard enough preparing data that makes the code happy so each bit of data requirement simplification will make a lot of people happy.

        It’s nice to know we can run the code on our own and get error messages that way, thanks. Please also do whatever you can to make it easier for Shapeways to surface the error messages that you’re producing. I don’t know where their difficulty lies but simply being told “You’re doing something wrong. Please guess again” gets old really fast.

      • Ah! I was missing awareness of abfab3d/svxconv. Very helpful! And what a silly mistake on the close quote.

        I’m intentionally doing a few weird things (like making Z up for now), but these will be fixed before sending it to fab.

        One curious question: What is the purpose of translating it back to triangles? I thought of SVX as being a near-raw (rasterized) format that goes straight to the printer. (My guess is the check-for-manufacturability tools expect a triangular mesh, which makes sense.)

        Thanks! Nicely designed file format, btw!

  13. Alan Hudson says:

    Several of our back-end tools are still triangle based so we need triangle representations for those. And sadly most of the printers we talk with are still triangle based as well. SVX is forward looking in its hopes of getting a direct voxel->printer pipeline going.


    • cutelyaware says:

      Forward looking is great but how can anti-aliased voxels help now if you’re always generating triangles?

      • Alan Hudson says:

        We experience a few benefits currently in our backend in terms of storage and compute required. That said right now because of the state of some tools and 3d printers you won’t experience too much benefit. But you will have your software well positioned as we line up the pieces. We are in active discussion with a few printer manufactures to get direct access using voxels. When that happens you’ll be able to blow past our current 2M triangle limit and provide printer resolution control. After that will come per-voxel level material control(though a few years out). My hope is to have the first printer lined up this year to allow direct access too.

        Antialiased voxels help us in generating lower poly count meshes. The more gradual the changes the better the voxel -> triangles algorithms work. Your voxels are describing the boundary between open space and your surface. Using 0.1mm voxels and binary values is basically 0.1mm accuracy. If instead you use 8 bit floats then we have 255 levels of accuracy to find the surface. Ie spend 8 bits instead of lowering the voxel size to say 0.05mm accuracy which grows the file much faster.

  14. Artem Grunichev says:

    Hello. Why voxels here are cubes? Many printers are able to make down to 0.2 mm thick layers, so there are no reason to make Z-size of voxels as low as 0.1 mm, while X and Y dimensions could need nicer resolution, like 0.05 mm, for good surface.

    • Alan Hudson says:

      The code is much easier using square voxels. Originally the abfab3d library supported different sliceHeights but it’s been lost over time. If other implementors of this format desire this feature we could discuss it. At least at the file format level we could likely pull some tricks to process this while not implementing at the lowest levels of our voxel handling.

  15. Michael Gallo says:

    In your example file, the slice naming scheme is “slice%4d.png”, yet the files are actually named “slice 0.png”, “slice 1.png” and so on (with a space between the name and the number).
    Does that mean the slices=”…” attribute is not really used when reading the files?

  16. Stony Smith says:

    Do you know if any visualization tools have been built that will run locally? Or, is our only option at this time to upload it to Shapeways to see it?

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s