richyshub / magicavoxel-vox-importer

Blender import script for MagicaVoxel .vox format as cube primitives.

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.

License

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

magicavoxel-vox-importer's Issues

X axis inverted

X axis of imported voxel model is reversed to that imported with COLLADA
Could also be issue with y direction, voxel import does not require the rotate the .dae does

No default palette

Default palette is well defined in the specification of the format, yet currently we do not use this, we simply expect a palette chunk to be present in the .vox file

Extended vox format not supported

After import *.vox nothing happend and got "Unknown Chunk id nTRN" in console.

Blender 3.0.0 Error, MagicaVoxel-0.99.7.0-win64

Python: Traceback (most recent call last):
File "C:\Users\User\AppData\Roaming\Blender Foundation\Blender\3.0\scripts\addons\io_scene_vox.py", line 126, in execute
import_vox(path, **keywords)
File "C:\Users\User\AppData\Roaming\Blender Foundation\Blender\3.0\scripts\addons\io_scene_vox.py", line 180, in import_vox
assert (struct.unpack('<4ci', vox.read(8)) == (b'V', b'O', b'X', b' ', 150))
AssertionError

location: :-1

Importing Procedure

You're project seems really interesting for it's material physics based import!

I copied the script into the text editor of blender and ran it but it's unclear how it works. Can someone clarify the procedure for importing a file after properly exporting to the vox (old format) in magica voxel?

Cycles Render?

Current plan is to use the Blender internal renderer, and material system.

Would be nice to also support cycles nodes system.
This would allow us to also support glow, via some compositing node tricks?

Washed out

Palette Branch
Colors, when compared to the COLLADA import seem really washed out.
Perhaps looking at a vox model that runs the full gamut would help diagnose

Join objects (and/or boolean union) by material

How to reduce number of vertices/faces for "high voxels" models?
How to speed-up objects roto-translations for new scene-graph structure?

• Boolean modifiers (union)? Slow while setting up the scene in Blender and uncomfortable: you have to set a single modifier for each pair of "voxel" first, apply it to remove "merged" voxel then. Pay attention to multi-materials objects.

• Join multiple objects/voxels: easy, fast, but it does not reduce number of polygons.

Cannot find in Addons, Blender 2.92.0

Probably caused by the update, but I've installed it, but it won't come up in Blender. Any suggestions or help is appreciated.

No material support

Materials saved in the .vox format are not processed.

Import issue

I downloaded and enabled addon, entry in menu "Import" has appeared, when I tried importing model from .vox file and nothing happened. No model imported. Please help.

Blender version: 2.80.75. Latest version of addon (2.1)
MagicaVoxel version: 0.99.4.2

Thanks.

Extended vox format scene structure is not supported.

The extension to the .vox format added several chunks that deal with the layout of the scene.

Namely, these define a scene graph containing grouped content, that then can be part of other groups, or be transformed.

This is not appreciably replicated in the blender import, although it could be.

I believe that in Blender>2.80, this maps nicely to the collections system.

However, I don't believe collection objects themselves can be transformed, so these would be applied through the tree.

example scene graph from the spec.

=================================
(d) Scene Graph

T : Transform Node
G : Group Node
S : Shape Node

     T
     |
     G
    / \
   T   T
   |   |
   G   S
  / \
 T   T
 |   |
 S   S

=================================

Frame-based animations

Shorlty: I think we should load the first (or a specific) frame instead of loading all of them (see SIZE and XYZI for old file format).

See also on YouTube: Magicavoxel Frame Based Animation - Tutorial

Chunk 'MAIN'
{
    // pack of models
    Chunk 'PACK'    : optional

    // models (or FRAMES)
    // First FRAME
    Chunk 'SIZE'
    Chunk 'XYZI'

    // Second FRAME
    Chunk 'SIZE'
    Chunk 'XYZI'

    ...
}

We are drawing all voxels, all frames now (deer.vox): first frame to the left (355 voxels) vs all frames (1415 voxels).

Here we can look for a "specific" frame voxels:

        current_frame = 0  # MagicaVoxels frames are 0-based
        
        while True:
        ...

            elif name == 'XYZI':
                # voxel data, READ ALWAYS for all frames, but...
                num_voxels, = struct.unpack('<i', vox.read(4))
                for voxel in range(num_voxels):
                    voxel_data = struct.unpack('<4B', vox.read(4))
                    # ...stores them for a SPECIFIC or first frame ONLY
                    voxels.append(voxel_data)

For example:

                # voxel data
                if load_frame == current_frame:
                    num_voxels, = struct.unpack('<i', vox.read(4))
                    for voxel in range(num_voxels):
                        voxel_data = struct.unpack('<4B', vox.read(4))
                        voxels.append(voxel_data)
                else:
                    print("Skipping voxels in frame #{}".format(current_frame))
                    vox.read(s_self)
                current_frame = current_frame + 1

About error handling:

• What if VOX file has less frames?
• Should we "preload" VOX, I mean before main loop, to count number of frames and halt in error?

Cannot Install Addon on Blender 3.3

The addon cannot be installed on Blender 3.3

Lack of testing

The current project has no formal testing framework.

As more features are added, or further format revisions are supported, this is going to become a bigger issue.

Testing is currently quite difficult without extensively mocking the bpy module, and having a deep understanding of how it behaves, while also tracking the scene state.

One option to remedy this might be a separation of parsing and creating,

• Parse .vox file into an internal representation
• Export internal representation

This might make testing easier, given an internal representation of the entire scene is available.

Dead project?

Hello, this looks super useful! Any chance this will be updated to support the new multi-object world format with material properties conversion? Honestly I'd be willing to buy that.

Materials are difficult to navigate

All materials are imported with uninspiring names.

This issue is to discuss how we could approach this, giving unique, meaningful names to imported materials.