MagicaVoxel-VOX-importer

Blender import add-on for MagicaVoxel .vox format.

MagicaVoxel and other voxel editing software are great to quickly create voxel models, though it's not always desirable to stay within that ecosystem. This add-on imports each voxel of the original model as an individual cube primitive. This opens up the use of voxel models for projects such as physics simulations.

Getting Started

Installation

This add-on needs to be installed into Blender in order to be used. Directions for this process can be found here directly from the Blender Documentation.

Only io_scene_vox.py need be installed, other files in this repository are not functionally required.

Note: in order to enable the add-on, you will need to have Testing add-ons visible within the Blender Preferences menu.

Usage

With the add-on installed and enabled, the importer can be accessed from File > Import > MagicaVoxel (.vox)

Note: currently this add-on does not support all the features of .vox files created with MagicaVoxel 0.99 and above. If this is the version of MagicaVoxel you are using, you will need to export your file to the older 0.98 format before import.

This export is destructive, it will remove layer information and other features that were added in 0.99. It is therefore recommended you export as a separate filename so as to not lose work.

Import options

This add-on offers several import options, seen on the file select menu of the import.

• Voxel Spacing: controls distance center to center of neighbouring voxels.
• Voxel Size: how large each voxel should be, in Blender Units.
• Animation frame to load: for .vox files that contain animation frames, only 1 frame may be imported at a time, this option selects that value. If a value is given that exceeds the final frame, the final frame is used instead.
• Use Voxel Bounds: import only a sub-set of the model, potentially useful for loading larger models.
  • Start Voxel / End Voxel: define which voxels to import.
• Use Palette Colors: should the colors present in the .vox file be imported as materials?
• Gamma Correct Colors: in order to reproduce colors in the render, colors in the palette are gamma corrected. Disabling this will likely cause discoloration compared to the model when viewed in MagicaVoxel.
  • Gamma Correction Value: value of color correction, default of 2.2, see here for more information.
• Use Shadeless Materials: makes materials 'shadeless' by changing the material type to emissive.
• Join Voxels: currently naïve option to perform a join operation on the voxels after import. This will make manipulating the model much more performant, though is not suitable in all cases, i.e. physics simulations.

Questions and Concerns

If in using this add-on you encounter difficulties, be sure to check the issues, in case a solution has been outlined there. If not, then issues are welcomed.

Changelog and Versioning

The changes made to this repository are documented in the CHANGELOG. This repository uses SemVer for versioning. For the versions available, see the tags on this repository.

Known issues

• Some materials (like clouds) don't work or are untested for conversion
• README needs to be updated to keep up with this fork
• Blender operators (calls starting with bpy.ops) should be replaced with their back-end equivalents. This is because operators trigger a scene update every time they are called, which slows down importing after many operations.
• Need to add unit testing at least

If you can assist with any of these, open a pull request!

License

This project is licensed under the MIT License - see the LICENSE file for details