.\" This man page was written by Martin Gerhardy in May 2020. It is provided
.\" under the GNU General Public License 3 or (at your option) any later version.
.TH @COMMANDLINE@ "1" "May 2020" "@COMMANDLINE@"
.SH NAME
@COMMANDLINE@ \- convert, export or modify voxel volumes

.SH SYNOPSIS
.PP
\fB@NAME@\fR [\fIoption\fR] --input infile --output outfile
.SH DESCRIPTION
\fB@COMMANDLINE@\fP is a command line application that can convert several voxel
volume formats into others. Supported formats are e.g. cub (CubeWorld), qb/qbt
(Qubicle), vox (MagicaVoxel), vmx (VoxEdit Sandbox), kvx (Build engine), kv6 (SLAB6),
binvox and others. It can also export to mesh formats like obj, gltf, stl and ply with
a number of options.
.SH OPTIONS

.TP
\fB\--crop\fR
Reduces the volume sizes to their voxel boundaries.

.TP
\fB\--dump\fR
Dump the scene graph of the input file.

.TP
\fB\--export-palette\fR
Export the used palette data into an image.

.TP
\fB\--export-layers\fR
Export all the layers of a scene into single files. It is suggested to name the layers
properly to get reasonable file names.

.TP
\fB\--filter <filter>\fR
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 as 1,2,4. The first layer is 0.

.TP
\fB\--force|-f\fR
Overwrite existing files.

.TP
\fB\--image-as-heightmap\fR
Import input images as heightmaps (default).

.TP
\fB\--image-as-plane\fR
Import input images as planes.

.TP
\fB\--image-as-volume\fR
Import given input image as volume. Uses a depth map to make a volume out of the
image. The depth map R channel is using values from 0 (black) to white (255)
resulting in voxel heights from 1 to max-height (see --image-as-volume-max-depth).

The \fB\--input\fR with e.g. \fBsomeimage.png\fR will pick the depth map next to
the image path called \fBsomeimage-dm.png\fR as depth map.

.TP
\fB\--image-as-volume-max-depth\fR
Default is 8 - see --image-as-volume.

.TP
\fB\--image-as-volume-both-sides\fR
Importing image as volume and use the depth map for both sides.

.TP
\fB\--input|-i <file>\fR
Allow to specify input files.

.TP
\fB\--merge|-m\fR
Merge all layers into one. Some destination formats only support one layer - for
those formats this is an explicit parameter. If you are going to export to a mesh
format like wavefront obj, this option changes the behaviour of the exporter, too.

.TP
\fB\--mirror <x|y|z>\fR
Mirror by the given axis (x, y or z).

.TP
\fB\--output|-o <file>\fR
Allow to specify the output file.

.TP
\fB\--pivot <x:y:z>\fR
Change the pivot of the volume layers.

Not all voxel formats support this.

.TP
\fB\--resize <x:y:z>\fR
Resize the volume by the given x (right), y (up) and z (back) values.

.TP
\fB\--rotate <x|y|z>\fR
Rotate by 90 degree at the given axis (x, y or z).

.TP
\fB\--scale|-s\fR
Save the target volume with a down-sampled version of the input volume.

.TP
\fB\--script "<script> <args>"\fR
Apply the given lua script to the output volume.

.TP
\fB\--split <x:y:z>\fR
Slices the volumes into pieces of the given size

.TP
\fB\--translate|-t <x:y:z>\fR
Translate the volumes by x (right), y (up), z (back).

.TP
\fB\--help\fR
Print usage information with a a full list of cvars

.TP
\fB\-set <varname> <value>\fR
Change the value of a config variable. \fB-set palette /path/to/palette.png\fR is
going to use a different palette for importing and exporting the voxels. It should
have the dimensions 1x256.

.TP
\fB\--trace|--debug|--info\fR
Enable trace, debug or info logging

.TP
\fB\--version|-v\fR
Print the version of the application.

.SH ORDER OF EXECUTION

.TP
filter
.TP
merge
.TP
scale
.TP
mirror
.TP
rotate
.TP
translate
.TP
script
.TP
pivot
.TP
crop
.TP
split

.SH LOAD
.TP
Qubicle Binary (*.qb)
.TP
MagicaVoxel (*.vox)
.TP
Qubicle Binary Tree (*.qbt)
.TP
Qubicle Project (*.qbcl)
.TP
Sandbox VoxEdit Collection (*.vxc)
.TP
Sandbox VoxEdit Model (*.vxm)
.TP
Sandbox VoxEdit Hierarchy (*.vxr)
.TP
Sandbox VoxEdit Tileset (*.vxt)
.TP
Minecraft Region (*.mca)
.TP
BinVox (*.binvox)
.TP
Goxel (*.gox)
.TP
CubeWorld (*.cub)
.TP
Sproxel csv (*.csv)
.TP
Build engine (*.kvx)
.TP
Ace of Spades (*.kv6)
.TP
Tiberian Sun (*.vxl)
.TP
AceOfSpades (*.vxl)
.TP
Qubicle Exchange (*.qef)
.TP
Chronovox (*.csm)
.TP
Nicks Voxel Model (*.nvm)
.TP
Wavefront Object (*.obj)
.TP
Standard Triangle Language (*.stl)

.SH SAVE
.TP
Qubicle Binary (*.qb)
.TP
MagicaVoxel (*.vox)
.TP
Qubicle Binary Tree (*.qbt)
.TP
Sandbox VoxEdit Model (*.vxm)
.TP
Sandbox VoxEdit Hierarchy (*.vxr)
.TP
BinVox (*.binvox)
.TP
Goxel (*.gox)
.TP
Sproxel csv (*.csv)
.TP
CubeWorld (*.cub)
.TP
Tiberian Sun (*.vxl)
.TP
Qubicle Exchange (*.qef)
.TP
Wavefront Object (*.obj)
.TP
Polygon File Format (*.ply)
.TP
Standard Triangle Language (*.stl)
.TP
GL Transmission Format (*.gltf)

.SH 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.

.SH EXAMPLES

.SS Level of detail (LOD)
Generate a lod scaled by 50% from the input model:

\fB@NAME@ -s --input infile.vox output.vox\fP

.SS Merge several models
Merge several models into one:

\fB@NAME@ --input one.vox --input two.vox --output onetwo.vox\fP

.SS Generate from heightmap
Just specify the heightmap as input file like this:

\fB@NAME@ --input heightmap.png --output outfile.vox\fP

.SS Translate the voxels
You can translate the voxels in the world like this:

\fB@NAME@ --translate 0:10:0 --input heightmap.png --output outfile.vox\fP

This would move the voxels 10 units upwards. But keep in mind that not every format supports to store a translation offset.

.SS Execute lua script
Use the \fB--script\fP parameter:

\fB@NAME@ --script "cover 2" --input infile.vox --output outfile.vox\fP

This is executing the script in \fB./scripts/cover.lua\fP with a parameter of \fB2\fP.

\fB@NAME@ --script "./scripts/cover.lua 2" --input infile.vox --output outfile.vox\fP

This is doing exactly the same as above - just with a full path.

The scripting docs are available at https://mgerhardy.github.io/vengi/LUAScript/.

.SS Extract palette png
Saves the png in the same dir as the vox file:

\fB@NAME@ --export-palette --input infile.vox --output outfile.vox\fP

There will be an \fBinfile.png\fP now.

.SS Extract single layers
Extract just a few layers from the input file.

\fB@NAME@ --filter 1-2,4 --input infile.vox --output outfile.vox\fP

This will export layers 1, 2 and 4.

.SS Convert to mesh
You can export your volume model into a obj or ply.

\fB@NAME@ --input infile.vox --output outfile.obj\fP

Config vars to control the meshing:

.PP
\fBvoxformat_ambientocclusion\fP: Don't export extra quads for ambient occlusion voxels
.PP
\fBvoxformat_mergequads\fP: Merge similar quads to optimize the mesh
.PP
\fBvoxformat_reusevertices\fP: Reuse vertices or always create new ones
.PP
\fBvoxformat_scale\fP: Scale the vertices on all axis by the given factor
.PP
\fBvoxformat_scale_x\fP: Scale the vertices on X axis by the given factor
.PP
\fBvoxformat_scale_y\fP: Scale the vertices on Y axis by the given factor
.PP
\fBvoxformat_scale_z\fP: Scale the vertices on Z axis by the given factor
.PP
\fBvoxformat_quads\fP: Export to quads
.PP
\fBvoxformat_withcolor\fP: Export vertex colors
.PP
\fBvoxformat_withtexcoords\fP: Export texture coordinates
.PP
\fBvoxformat_transform_mesh\fP: Apply the keyframe transforms to the mesh

.SH HOMEPAGE
https://github.com/mgerhardy/vengi

.SH COPYRIGHT
Copyright \[co] 2015\-2022 by Martin Gerhardy.

.SH BUGS
If you find a bug, please report it at https://github.com/mgerhardy/vengi/issues