2020-05-17 08:42:43 -07:00
|
|
|
.\" 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.
|
2021-12-21 13:50:05 -08:00
|
|
|
.TH @COMMANDLINE@ "1" "May 2020" "@COMMANDLINE@"
|
2020-05-17 08:42:43 -07:00
|
|
|
.SH NAME
|
2021-12-21 13:50:05 -08:00
|
|
|
@COMMANDLINE@ \- convert, export or modify voxel volumes
|
2020-05-17 08:42:43 -07:00
|
|
|
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.PP
|
2021-12-21 08:07:34 -08:00
|
|
|
\fB@NAME@\fR [\fIoption\fR] --input infile --output outfile
|
2020-05-17 08:42:43 -07:00
|
|
|
.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
|
2020-05-24 12:35:02 -07:00
|
|
|
(Qubicle), vox (MagicaVoxel), vmx (VoxEdit Sandbox), kvx (Build engine), kv6 (SLAB6),
|
2022-03-08 07:21:43 -08:00
|
|
|
binvox and others. It can also export to mesh formats like obj, gltf, stl and ply with
|
|
|
|
a number of options.
|
2020-05-17 08:42:43 -07:00
|
|
|
.SH OPTIONS
|
2022-01-05 02:52:44 -08:00
|
|
|
|
|
|
|
.TP
|
|
|
|
\fB\--crop\fR
|
|
|
|
Reduces the volume sizes to their voxel boundaries.
|
|
|
|
|
2022-01-19 10:25:18 -08:00
|
|
|
.TP
|
|
|
|
\fB\--dump\fR
|
|
|
|
Dump the scene graph of the input file.
|
|
|
|
|
2020-05-17 08:42:43 -07:00
|
|
|
.TP
|
2021-12-21 13:50:05 -08:00
|
|
|
\fB\--export-palette\fR
|
2022-05-23 11:21:36 -07:00
|
|
|
Export the used palette data into an image.
|
2021-12-21 13:50:05 -08:00
|
|
|
|
2022-01-15 01:38:49 -08:00
|
|
|
.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.
|
|
|
|
|
2021-12-21 13:50:05 -08:00
|
|
|
.TP
|
2022-01-05 02:52:44 -08:00
|
|
|
\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.
|
2021-12-21 13:50:05 -08:00
|
|
|
|
|
|
|
.TP
|
|
|
|
\fB\--force|-f\fR
|
|
|
|
Overwrite existing files.
|
|
|
|
|
2022-03-15 23:54:08 -07:00
|
|
|
.TP
|
|
|
|
\fB\--image-as-heightmap\fR
|
|
|
|
Import input images as heightmaps (default).
|
|
|
|
|
|
|
|
.TP
|
|
|
|
\fB\--image-as-plane\fR
|
|
|
|
Import input images as planes.
|
|
|
|
|
2022-03-31 13:57:46 -07:00
|
|
|
.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.
|
|
|
|
|
2021-12-21 13:50:05 -08:00
|
|
|
.TP
|
2022-01-05 02:52:44 -08:00
|
|
|
\fB\--input|-i <file>\fR
|
2021-12-21 13:50:05 -08:00
|
|
|
Allow to specify input files.
|
2020-05-17 08:42:43 -07:00
|
|
|
|
2020-05-24 09:22:01 -07:00
|
|
|
.TP
|
|
|
|
\fB\--merge|-m\fR
|
|
|
|
Merge all layers into one. Some destination formats only support one layer - for
|
2020-10-03 04:10:42 -07:00
|
|
|
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.
|
2020-05-24 09:22:01 -07:00
|
|
|
|
2021-12-21 13:50:05 -08:00
|
|
|
.TP
|
2022-01-05 02:52:44 -08:00
|
|
|
\fB\--mirror <x|y|z>\fR
|
2021-12-21 13:50:05 -08:00
|
|
|
Mirror by the given axis (x, y or z).
|
|
|
|
|
|
|
|
.TP
|
2022-01-05 02:52:44 -08:00
|
|
|
\fB\--output|-o <file>\fR
|
2021-12-21 13:50:05 -08:00
|
|
|
Allow to specify the output file.
|
|
|
|
|
2021-12-22 07:07:11 -08:00
|
|
|
.TP
|
2022-01-05 02:52:44 -08:00
|
|
|
\fB\--pivot <x:y:z>\fR
|
2021-12-22 07:07:11 -08:00
|
|
|
Change the pivot of the volume layers.
|
|
|
|
|
|
|
|
Not all voxel formats support this.
|
|
|
|
|
2022-01-21 13:19:19 -08:00
|
|
|
.TP
|
|
|
|
\fB\--resize <x:y:z>\fR
|
|
|
|
Resize the volume by the given x (right), y (up) and z (back) values.
|
|
|
|
|
2021-12-21 13:50:05 -08:00
|
|
|
.TP
|
2022-01-05 02:52:44 -08:00
|
|
|
\fB\--rotate <x|y|z>\fR
|
2021-12-21 13:50:05 -08:00
|
|
|
Rotate by 90 degree at the given axis (x, y or z).
|
|
|
|
|
2020-05-24 09:22:01 -07:00
|
|
|
.TP
|
|
|
|
\fB\--scale|-s\fR
|
|
|
|
Save the target volume with a down-sampled version of the input volume.
|
|
|
|
|
2021-12-21 13:50:05 -08:00
|
|
|
.TP
|
2022-01-05 02:52:44 -08:00
|
|
|
\fB\--script "<script> <args>"\fR
|
2021-12-21 13:50:05 -08:00
|
|
|
Apply the given lua script to the output volume.
|
|
|
|
|
2022-01-05 02:52:44 -08:00
|
|
|
.TP
|
|
|
|
\fB\--split <x:y:z>\fR
|
|
|
|
Slices the volumes into pieces of the given size
|
|
|
|
|
2021-12-21 13:50:05 -08:00
|
|
|
.TP
|
2022-01-05 02:52:44 -08:00
|
|
|
\fB\--translate|-t <x:y:z>\fR
|
2021-12-21 13:50:05 -08:00
|
|
|
Translate the volumes by x (right), y (up), z (back).
|
|
|
|
|
|
|
|
.TP
|
|
|
|
\fB\--help\fR
|
|
|
|
Print usage information with a a full list of cvars
|
|
|
|
|
2020-10-03 04:10:42 -07:00
|
|
|
.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.
|
|
|
|
|
2021-12-21 13:50:05 -08:00
|
|
|
.TP
|
|
|
|
\fB\--trace|--debug|--info\fR
|
|
|
|
Enable trace, debug or info logging
|
|
|
|
|
2020-10-03 04:10:42 -07:00
|
|
|
.TP
|
|
|
|
\fB\--version|-v\fR
|
|
|
|
Print the version of the application.
|
|
|
|
|
2022-01-05 02:52:44 -08:00
|
|
|
.SH ORDER OF EXECUTION
|
|
|
|
|
|
|
|
.TP
|
|
|
|
filter
|
|
|
|
.TP
|
|
|
|
merge
|
|
|
|
.TP
|
|
|
|
scale
|
|
|
|
.TP
|
|
|
|
mirror
|
|
|
|
.TP
|
|
|
|
rotate
|
|
|
|
.TP
|
|
|
|
translate
|
|
|
|
.TP
|
|
|
|
script
|
|
|
|
.TP
|
|
|
|
pivot
|
|
|
|
.TP
|
|
|
|
crop
|
|
|
|
.TP
|
|
|
|
split
|
|
|
|
|
2021-12-21 13:50:05 -08:00
|
|
|
.SH LOAD
|
2020-05-17 08:42:43 -07:00
|
|
|
.TP
|
2021-12-21 13:50:05 -08:00
|
|
|
Qubicle Binary (*.qb)
|
|
|
|
.TP
|
|
|
|
MagicaVoxel (*.vox)
|
|
|
|
.TP
|
|
|
|
Qubicle Binary Tree (*.qbt)
|
|
|
|
.TP
|
|
|
|
Qubicle Project (*.qbcl)
|
|
|
|
.TP
|
2022-02-09 11:56:20 -08:00
|
|
|
Sandbox VoxEdit Collection (*.vxc)
|
|
|
|
.TP
|
2021-12-21 13:50:05 -08:00
|
|
|
Sandbox VoxEdit Model (*.vxm)
|
|
|
|
.TP
|
2022-01-15 00:55:35 -08:00
|
|
|
Sandbox VoxEdit Hierarchy (*.vxr)
|
2021-12-21 13:50:05 -08:00
|
|
|
.TP
|
2022-02-09 12:39:59 -08:00
|
|
|
Sandbox VoxEdit Tileset (*.vxt)
|
|
|
|
.TP
|
2022-01-14 11:57:39 -08:00
|
|
|
Minecraft Region (*.mca)
|
|
|
|
.TP
|
2021-12-21 13:50:05 -08:00
|
|
|
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)
|
2022-03-07 14:14:24 -08:00
|
|
|
.TP
|
|
|
|
Wavefront Object (*.obj)
|
2022-03-08 07:56:59 -08:00
|
|
|
.TP
|
|
|
|
Standard Triangle Language (*.stl)
|
2021-12-21 13:50:05 -08:00
|
|
|
|
|
|
|
.SH SAVE
|
|
|
|
.TP
|
|
|
|
Qubicle Binary (*.qb)
|
|
|
|
.TP
|
|
|
|
MagicaVoxel (*.vox)
|
|
|
|
.TP
|
|
|
|
Qubicle Binary Tree (*.qbt)
|
|
|
|
.TP
|
|
|
|
Sandbox VoxEdit Model (*.vxm)
|
|
|
|
.TP
|
2022-01-15 00:55:35 -08:00
|
|
|
Sandbox VoxEdit Hierarchy (*.vxr)
|
2021-12-21 13:50:05 -08:00
|
|
|
.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)
|
2022-03-08 07:56:59 -08:00
|
|
|
.TP
|
|
|
|
Standard Triangle Language (*.stl)
|
2022-03-08 07:21:43 -08:00
|
|
|
.TP
|
|
|
|
GL Transmission Format (*.gltf)
|
2021-12-21 13:50:05 -08:00
|
|
|
|
2022-01-05 02:52:44 -08:00
|
|
|
.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.
|
|
|
|
|
2021-12-21 13:50:05 -08:00
|
|
|
.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.
|
|
|
|
|
2022-01-23 14:22:47 -08:00
|
|
|
The scripting docs are available at https://mgerhardy.github.io/vengi/LUAScript/.
|
2021-12-21 13:50:05 -08:00
|
|
|
|
|
|
|
.SS Extract palette png
|
|
|
|
Saves the png in the same dir as the vox file:
|
|
|
|
|
2022-05-23 11:21:36 -07:00
|
|
|
\fB@NAME@ --export-palette --input infile.vox --output outfile.vox\fP
|
2021-12-21 13:50:05 -08:00
|
|
|
|
|
|
|
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
|
2022-03-05 07:04:22 -08:00
|
|
|
\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
|
2021-12-21 13:50:05 -08:00
|
|
|
.PP
|
|
|
|
\fBvoxformat_quads\fP: Export to quads
|
|
|
|
.PP
|
|
|
|
\fBvoxformat_withcolor\fP: Export vertex colors
|
|
|
|
.PP
|
|
|
|
\fBvoxformat_withtexcoords\fP: Export texture coordinates
|
2022-05-23 07:51:36 -07:00
|
|
|
.PP
|
|
|
|
\fBvoxformat_transform_mesh\fP: Apply the keyframe transforms to the mesh
|
2020-05-17 08:42:43 -07:00
|
|
|
|
|
|
|
.SH HOMEPAGE
|
2022-01-23 14:22:47 -08:00
|
|
|
https://github.com/mgerhardy/vengi
|
2020-05-17 08:42:43 -07:00
|
|
|
|
|
|
|
.SH COPYRIGHT
|
2021-12-21 13:44:49 -08:00
|
|
|
Copyright \[co] 2015\-2022 by Martin Gerhardy.
|
2021-12-21 13:50:05 -08:00
|
|
|
|
|
|
|
.SH BUGS
|
2022-01-23 14:22:47 -08:00
|
|
|
If you find a bug, please report it at https://github.com/mgerhardy/vengi/issues
|