5.5 KiB
General
Convert voxel volume formats between each other or export to obj or ply.
Usage
./vengi-voxconvert --merge --scale --input infile --output outfile
--export-palette
: will save the included palette as png next to the source file. Use in combination with--src-palette
.--filter <filter>
: will filter out layers not mentioned in the expression. E.g.1-2,4
will handle layer 1, 2 and 4. It is the same as1,2,4
. The first layer is0
. See the layers note below.--force
: overwrite existing files--input <file>
: allows to specify input files. You can specify more than one file--merge
: will merge a multi layer volume (like vox, qb or qbt) into a single volume of the target file--mirror <x|y|z>
: allows you to mirror the volumes at x, y and z axis--output <file>
: allows you to specify the output filename--pivot <x:y:z>
: change the pivots of the volume layers. Not all voxel formats support this.--rotate <x|y|z>
: allows you to rotate the volumes by 90 degree at x, y and z axis--scale
: perform lod conversion of the input volume (50% scale per call)--script "<script> <args>"
: execute the given script - see scripting support for more details--src-palette
: will use the included palette and doesn't perform any quantization to the default palette--translate <x:y:z>
: translates the volumes by x (right), y (up), z (back)
Just type vengi-voxconvert
to get a full list of commands and options.
Using a different target palette is also possible by setting the palette
config var.
./vengi-voxconvert -set palette /path/to/palette.png --input infile outfile
The palette file has to be in the dimensions 1x256. It is also possible to just provide the basename of the palette.
This is e.g. nippon
. The tool will then try to look up the file palette-nippon.png
in the file search paths.
You can convert to a different palette with this command. The closest possible color will be chosen for each color from the source file palette to the specified palette.
The order of execution is:
- filter
- merge
- scale
- mirror
- rotate
- translate
- script
- pivot
Layers
Some formats also have layer support. Our layers are maybe not the layers you know from your favorite editor. Each layer can currently only have one object or volume in it. To get the proper layer ids (starting from 0) for your voxel file, you should load it once in voxedit and check the layer panel.
Especially magicavoxel supports more objects in one layer. This might be confusing to get the right numbers for voxconvert
. See this issue for a few more details.
Level of detail (LOD)
Generate a lod scaled by 50% from the input model.
./vengi-voxconvert -s --input infile.vox output.vox
Merge several models
Merge several models into one:
./vengi-voxconvert --input one.vox --input two.vox --output onetwo.vox
Generate from heightmap
Just specify the heightmap as input file like this:
./vengi-voxconvert --input heightmap.png --output outfile.vox
Translate the voxels
You can translate the voxels in the world like this:
./vengi-voxconvert --translate 0:10:0 --input heightmap.png --output outfile.vox
This would move the voxels 10 units upwards. But keep in mind that not every format supports to store a translation offset.
Execute lua script
Use the --script
parameter:
./vengi-voxconvert --script "cover 2" --input infile.vox --output outfile.vox
This is executing the script in ./scripts/cover.lua
with a parameter of 2
.
./vengi-voxconvert --script "./scripts/cover.lua 2" --input infile.vox --output outfile.vox
This is doing exactly the same as above - just with a full path.
See the scripting documentation for further details.
Extract palette png
Saves the png in the same dir as the vox file:
./vengi-voxconvert --src-palette --export-palette --input infile.vox --output outfile.vox
There will be an infile.png
now.
Extract single layers
Extract just a few layers from the input file.
./vengi-voxconvert --filter 1-2,4 --input infile.vox --output outfile.vox
This will export layers 1, 2 and 4.
Convert to mesh
You can export your volume model into a obj or ply.
./vengi-voxconvert --input infile.vox --output outfile.obj
Config vars to control the meshing:
voxformat_ambientocclusion
: Don't export extra quads for ambient occlusion voxelsvoxformat_mergequads
: Merge similar quads to optimize the meshvoxformat_reusevertices
: Reuse vertices or always create new onesvoxformat_scale
: Scale the vertices by the given factorvoxformat_quads
: Export to quadsvoxformat_withcolor
: Export vertex colorsvoxformat_withtexcoords
: Export texture coordinates
See ./vengi-voxconvert --help
or configuration for more details.
Batch convert
To convert a complete directory of e.g. *.vox
to *.obj
files, you can use e.g. the bash like this:
for i in *.vox; do vengi-voxconvert --input $i --output ${i%.vox}.obj; done
An example for the windows powershell to extract single layers into a new model
$array = "1-2,5", "1-2,7"
foreach ($i in $array){
./vengi-voxconvert --filter $i --input input.vox --output output_$i.vxm
}