voxcity.exporter.magicavoxel

Module for handling MagicaVoxel .vox files.

This module provides functionality for converting 3D numpy arrays to MagicaVoxel .vox files, including color mapping and splitting large models into smaller chunks.

The module handles: - Color map conversion and optimization - Large model splitting into MagicaVoxel-compatible chunks - Custom palette creation - Coordinate system transformation - Batch export of multiple .vox files

Key Features: - Supports models larger than MagicaVoxel’s 256³ size limit - Automatic color palette optimization - Preserves color mapping across chunks - Handles coordinate system differences between numpy and MagicaVoxel

Classes

MagicaVoxelExporter

Exporter adapter to write VoxCity voxels as MagicaVoxel .vox chunks.

Functions

export_large_voxel_model(array, color_map, output_prefix)

Export a large voxel model by splitting it into multiple .vox files.

export_magicavoxel_vox(array, output_dir[, ...])

Export a voxel model to MagicaVoxel .vox format.

Module Contents

voxcity.exporter.magicavoxel.export_large_voxel_model(array, color_map, output_prefix, max_size=255, base_filename='chunk')[source]

Export a large voxel model by splitting it into multiple .vox files.

This function handles models of any size by: 1. Creating the output directory if needed 2. Splitting the model into manageable chunks 3. Saving each chunk as a separate .vox file 4. Maintaining consistent color mapping across all chunks

Parameters:

  • array (numpy.ndarray) – 3D array containing voxel data. Can be any size, will be split into chunks if needed.

  • color_map (dict) – Dictionary mapping indices to RGB color values. Each value should be a list of [R,G,B] values (0-255).

  • output_prefix (str) – Directory to save the .vox files. Will be created if it doesn’t exist.

  • max_size (int, optional) – Maximum size allowed for each dimension. Defaults to 255 (MagicaVoxel’s limit is 256).

  • base_filename (str, optional) – Base name for the output files. Defaults to ‘chunk’. Final filenames will be {base_filename}_{i}_{j}_{k}.vox

Returns:

(value_mapping, palette)

  • value_mapping: dict mapping original indices to MagicaVoxel indices

  • palette: numpy.ndarray of shape (256,4) containing RGBA values

Return type:

tuple

Example

>>> array = np.ones((500,500,500))
>>> color_map = {1: [255,0,0]}
>>> export_large_voxel_model(array, color_map, "output/model")
# Creates files like: output/model/chunk_0_0_0.vox, chunk_0_0_1.vox, etc.
voxcity.exporter.magicavoxel.export_magicavoxel_vox(array, output_dir, base_filename='chunk', voxel_color_map=None)[source]

Export a voxel model to MagicaVoxel .vox format.

This is the main entry point for voxel model export. It handles: 1. Color map management (using default if none provided) 2. Color index optimization 3. Large model splitting and export 4. Progress reporting

Parameters:

  • array (numpy.ndarray | VoxCity) – 3D array containing voxel data or a VoxCity instance. When a VoxCity is provided, its voxel classes are exported.

  • output_dir (str) – Directory to save the .vox files. Will be created if it doesn’t exist.

  • base_filename (str, optional) – Base name for the output files. Defaults to ‘chunk’. Used when model is split into multiple files.

  • voxel_color_map (dict, optional) – Dictionary mapping indices to RGB color values. If None, uses default color map from visualizer. Each value should be a list of [R,G,B] values (0-255).

Note

  • Large models are automatically split into multiple files

  • Color mapping is optimized and made sequential

  • Progress information is printed to stdout