2020-06-29 11:43:01 -07:00
# General
2020-09-16 10:30:55 -07:00
Convert voxel volume formats between each other or export to obj or ply.
2020-06-29 11:43:01 -07:00
2021-12-16 08:07:28 -08:00
* [Supported voxel formats ](../Formats.md )
* [Scripting support ](../LUAScript.md )
2020-11-30 15:11:20 -08:00
2020-06-29 12:37:14 -07:00
## Usage
`./vengi-voxconvert --merge --scale infile outfile`
2021-12-16 10:40:17 -08:00
* `--export-palette` : will save the included palette as png next to the source file. Use in combination with `--src-palette` .
2021-12-17 10:11:57 -08:00
* `--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 as `1,2,4` . The first layer is `0` .
2021-12-16 10:40:17 -08:00
* `--force` : overwrite existing files
2020-06-29 12:37:14 -07:00
* `--merge` : will merge a multi layer volume (like vox, qb or qbt) into a single volume of the target file
2021-12-17 14:31:50 -08:00
* `--mirror` : allows you to mirror the volumes at x, y and z axis
2021-12-17 14:35:22 -08:00
* `--rotate` : allows you to rotate the volumes by 90 degree at x, y and z axis
2020-06-29 12:37:14 -07:00
* `--scale` : perform lod conversion of the input volume (50% scale per call)
2021-12-16 10:40:17 -08:00
* `--script` : execute the given script - see [scripting support ](../LUAScript.md ) for more details
2021-11-30 14:06:27 -08:00
* `--src-palette` : will use the included palette and doesn't perform any quantization to the default palette
2020-06-29 12:37:14 -07:00
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 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.
2020-08-02 10:51:32 -07:00
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.
2020-09-16 10:39:36 -07:00
2021-12-16 08:07:28 -08:00
## Level of detail (LOD)
2020-11-13 10:40:39 -08:00
Generate a lod scaled by 50% from the input model.
`./vengi-voxconvert -s infile.vox lod1.vox`
2021-12-16 08:07:28 -08:00
## Generate from heightmap
2021-12-15 12:08:09 -08:00
Just specify the heightmap as input file like this:
`./vengi-voxconvert heightmap.png outfile.vox`
2021-12-16 08:07:28 -08:00
## Execute lua script
Use the `--script` parameter:
`./vengi-voxconvert --script "cover 2" infile.vox outfile.vox`
This is executing the script in `./scripts/cover.lua` with a parameter of `2` .
`./vengi-voxconvert --script "./scripts/cover.lua 2" infile.vox outfile.vox`
This is doing exactly the same as above - just with a full path.
See the [scripting ](../LUAScript.md ) documentation for further details.
## Extract palette png
2021-11-30 22:44:25 -08:00
Saves the png in the same dir as the vox file
`./vengi-voxconvert --src-palette --export-palette infile.vox outfile.vox`
There will be an `infile.png` now.
2021-12-17 06:46:55 -08:00
## Extract single layers
Extract just a few layers from the input file.
`./vengi-voxconvert --filter 1-2,4 infile.vox outfile.vox`
This will export layers 1, 2 and 4.
2021-12-16 08:07:28 -08:00
## Convert to mesh
2020-09-16 10:39:36 -07:00
You can export your volume model into a obj or ply.
`./vengi-voxconvert infile.vox outfile.obj`
2021-11-30 22:44:25 -08:00
Config vars to control the meshing:
2020-09-16 10:39:36 -07:00
2020-09-30 13:26:51 -07:00
* `voxformat_ambientocclusion` : Don't export extra quads for ambient occlusion voxels
2020-10-01 14:25:34 -07:00
* `voxformat_mergequads` : Merge similar quads to optimize the mesh
* `voxformat_reusevertices` : Reuse vertices or always create new ones
2020-09-30 13:26:51 -07:00
* `voxformat_scale` : Scale the vertices by the given factor
* `voxformat_quads` : Export to quads
2020-09-30 14:18:24 -07:00
* `voxformat_withcolor` : Export vertex colors
* `voxformat_withtexcoords` : Export texture coordinates
2020-09-16 10:39:36 -07:00
2021-11-30 22:44:25 -08:00
See `./vengi-voxconvert --help` or [configuration ](../Configuration.md ) for more details.
2020-10-01 14:23:46 -07:00
## Batch convert
To convert a complete directory of e.g. `*.vox` to `*.obj` files, you can use e.g. the bash like this:
```bash
for i in *.vox; do vengi-voxconvert $i ${i%.vox}.obj; done
```
2021-12-16 08:07:28 -08:00
2021-12-17 10:11:57 -08:00
An example for the windows powershell to extract single layers into a new model
```ps
$array = "1-2,5", "1-2,7"
foreach ($i in $array){
./vengi-voxconvert --filter $i input.vox output_$i.vxm
}
```
2021-12-16 08:07:28 -08:00
## Screenshots
![image ](https://raw.githubusercontent.com/wiki/mgerhardy/engine/images/voxconvert-export-to-obj.png )
![image ](https://raw.githubusercontent.com/wiki/mgerhardy/engine/images/voxconvert-export-obj.png )