voxcity.exporter.magicavoxel
============================

.. py:module:: voxcity.exporter.magicavoxel

.. autoapi-nested-parse::

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

.. toctree::
   :hidden:

   /autoapi/voxcity/exporter/magicavoxel/MagicaVoxelExporter

.. autoapisummary::

   voxcity.exporter.magicavoxel.MagicaVoxelExporter


Functions
---------

.. autoapisummary::

   voxcity.exporter.magicavoxel.export_large_voxel_model
   voxcity.exporter.magicavoxel.export_magicavoxel_vox


Module Contents
---------------

.. py:function:: export_large_voxel_model(array, color_map, output_prefix, max_size=255, base_filename='chunk')

   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

   :param array: 3D array containing voxel data.
                 Can be any size, will be split into chunks if needed.
   :type array: numpy.ndarray
   :param color_map: Dictionary mapping indices to RGB color values.
                     Each value should be a list of [R,G,B] values (0-255).
   :type color_map: dict
   :param output_prefix: Directory to save the .vox files.
                         Will be created if it doesn't exist.
   :type output_prefix: str
   :param max_size: Maximum size allowed for each dimension.
                    Defaults to 255 (MagicaVoxel's limit is 256).
   :type max_size: int, optional
   :param base_filename: Base name for the output files.
                         Defaults to 'chunk'. Final filenames will be {base_filename}_{i}_{j}_{k}.vox
   :type base_filename: str, optional

   :returns:

             (value_mapping, palette)
                 - value_mapping: dict mapping original indices to MagicaVoxel indices
                 - palette: numpy.ndarray of shape (256,4) containing RGBA values
   :rtype: tuple

   .. rubric:: 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.


.. py:function:: export_magicavoxel_vox(array, output_dir, base_filename='chunk', voxel_color_map=None)

   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

   :param array: 3D array containing voxel data or a VoxCity instance.
                 When a VoxCity is provided, its voxel classes are exported.
   :type array: numpy.ndarray | VoxCity
   :param output_dir: Directory to save the .vox files.
                      Will be created if it doesn't exist.
   :type output_dir: str
   :param base_filename: Base name for the output files.
                         Defaults to 'chunk'. Used when model is split into multiple files.
   :type base_filename: str, optional
   :param voxel_color_map: 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).
   :type voxel_color_map: dict, optional

   .. note::

      - Large models are automatically split into multiple files
      - Color mapping is optimized and made sequential
      - Progress information is printed to stdout