MagicaVoxel File: Python parsing library

Application

MagicaVoxel

File extension

vox

KS implementation details

License: MIT

This page hosts a formal specification of MagicaVoxel File using Kaitai Struct. This specification can be automatically translated into a variety of programming languages to get a parsing library.

Usage

Parse a local file and get structure in memory:

data = Vox.from_file("path/to/local/file.vox")

Or parse structure from a bytes:

from kaitaistruct import KaitaiStream, BytesIO

raw = b"\x00\x01\x02..."
data = Vox(KaitaiStream(BytesIO(raw)))

After that, one can get various attributes from the structure by invoking getter methods like:

data.version # => 150 expected

Python source code to parse MagicaVoxel File

vox.py

# This is a generated file! Please edit source .ksy file and use kaitai-struct-compiler to rebuild

from pkg_resources import parse_version
from kaitaistruct import __version__ as ks_version, KaitaiStruct, KaitaiStream, BytesIO
from enum import Enum


if parse_version(ks_version) < parse_version('0.7'):
    raise Exception("Incompatible Kaitai Struct Python API: 0.7 or later is required, but you have %s" % (ks_version))

class Vox(KaitaiStruct):
    """
    .. seealso::
       Format Description - https://github.com/ephtracy/voxel-model/blob/master/MagicaVoxel-file-format-vox.txt
    """

    class ChunkType(Enum):
        main = 1296124238
        matt = 1296127060
        pack = 1346454347
        rgba = 1380401729
        size = 1397316165
        xyzi = 1482250825

    class MaterialType(Enum):
        diffuse = 0
        metal = 1
        glass = 2
        emissive = 3

    class PropertyBitsType(Enum):
        plastic = 1
        roughness = 2
        specular = 4
        ior = 8
        attenuation = 16
        power = 32
        glow = 64
        is_total_power = 128
    def __init__(self, _io, _parent=None, _root=None):
        self._io = _io
        self._parent = _parent
        self._root = _root if _root else self
        self._read()

    def _read(self):
        self.magic = self._io.ensure_fixed_contents(b"\x56\x4F\x58\x20")
        self.version = self._io.read_u4le()
        self.main = self._root.Chunk(self._io, self, self._root)

    class Chunk(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.chunk_id = self._root.ChunkType(self._io.read_u4be())
            self.num_bytes_of_chunk_content = self._io.read_u4le()
            self.num_bytes_of_children_chunks = self._io.read_u4le()
            if self.num_bytes_of_chunk_content != 0:
                _on = self.chunk_id
                if _on == self._root.ChunkType.size:
                    self._raw_chunk_content = self._io.read_bytes(self.num_bytes_of_chunk_content)
                    io = KaitaiStream(BytesIO(self._raw_chunk_content))
                    self.chunk_content = self._root.Size(io, self, self._root)
                elif _on == self._root.ChunkType.matt:
                    self._raw_chunk_content = self._io.read_bytes(self.num_bytes_of_chunk_content)
                    io = KaitaiStream(BytesIO(self._raw_chunk_content))
                    self.chunk_content = self._root.Matt(io, self, self._root)
                elif _on == self._root.ChunkType.xyzi:
                    self._raw_chunk_content = self._io.read_bytes(self.num_bytes_of_chunk_content)
                    io = KaitaiStream(BytesIO(self._raw_chunk_content))
                    self.chunk_content = self._root.Xyzi(io, self, self._root)
                elif _on == self._root.ChunkType.pack:
                    self._raw_chunk_content = self._io.read_bytes(self.num_bytes_of_chunk_content)
                    io = KaitaiStream(BytesIO(self._raw_chunk_content))
                    self.chunk_content = self._root.Pack(io, self, self._root)
                elif _on == self._root.ChunkType.rgba:
                    self._raw_chunk_content = self._io.read_bytes(self.num_bytes_of_chunk_content)
                    io = KaitaiStream(BytesIO(self._raw_chunk_content))
                    self.chunk_content = self._root.Rgba(io, self, self._root)
                else:
                    self.chunk_content = self._io.read_bytes(self.num_bytes_of_chunk_content)

            if self.num_bytes_of_children_chunks != 0:
                self.children_chunks = []
                i = 0
                while not self._io.is_eof():
                    self.children_chunks.append(self._root.Chunk(self._io, self, self._root))
                    i += 1




    class Size(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.size_x = self._io.read_u4le()
            self.size_y = self._io.read_u4le()
            self.size_z = self._io.read_u4le()


    class Rgba(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.colors = [None] * (256)
            for i in range(256):
                self.colors[i] = self._root.Color(self._io, self, self._root)



    class Pack(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.num_models = self._io.read_u4le()


    class Matt(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.id = self._io.read_u4le()
            self.material_type = self._root.MaterialType(self._io.read_u4le())
            self.material_weight = self._io.read_f4le()
            self.property_bits = self._io.read_u4le()
            if self.has_plastic:
                self.plastic = self._io.read_f4le()

            if self.has_roughness:
                self.roughness = self._io.read_f4le()

            if self.has_specular:
                self.specular = self._io.read_f4le()

            if self.has_ior:
                self.ior = self._io.read_f4le()

            if self.has_attenuation:
                self.attenuation = self._io.read_f4le()

            if self.has_power:
                self.power = self._io.read_f4le()

            if self.has_glow:
                self.glow = self._io.read_f4le()

            if self.has_is_total_power:
                self.is_total_power = self._io.read_f4le()


        @property
        def has_is_total_power(self):
            if hasattr(self, '_m_has_is_total_power'):
                return self._m_has_is_total_power if hasattr(self, '_m_has_is_total_power') else None

            self._m_has_is_total_power = (self.property_bits & 128) != 0
            return self._m_has_is_total_power if hasattr(self, '_m_has_is_total_power') else None

        @property
        def has_plastic(self):
            if hasattr(self, '_m_has_plastic'):
                return self._m_has_plastic if hasattr(self, '_m_has_plastic') else None

            self._m_has_plastic = (self.property_bits & 1) != 0
            return self._m_has_plastic if hasattr(self, '_m_has_plastic') else None

        @property
        def has_attenuation(self):
            if hasattr(self, '_m_has_attenuation'):
                return self._m_has_attenuation if hasattr(self, '_m_has_attenuation') else None

            self._m_has_attenuation = (self.property_bits & 16) != 0
            return self._m_has_attenuation if hasattr(self, '_m_has_attenuation') else None

        @property
        def has_power(self):
            if hasattr(self, '_m_has_power'):
                return self._m_has_power if hasattr(self, '_m_has_power') else None

            self._m_has_power = (self.property_bits & 32) != 0
            return self._m_has_power if hasattr(self, '_m_has_power') else None

        @property
        def has_roughness(self):
            if hasattr(self, '_m_has_roughness'):
                return self._m_has_roughness if hasattr(self, '_m_has_roughness') else None

            self._m_has_roughness = (self.property_bits & 2) != 0
            return self._m_has_roughness if hasattr(self, '_m_has_roughness') else None

        @property
        def has_specular(self):
            if hasattr(self, '_m_has_specular'):
                return self._m_has_specular if hasattr(self, '_m_has_specular') else None

            self._m_has_specular = (self.property_bits & 4) != 0
            return self._m_has_specular if hasattr(self, '_m_has_specular') else None

        @property
        def has_ior(self):
            if hasattr(self, '_m_has_ior'):
                return self._m_has_ior if hasattr(self, '_m_has_ior') else None

            self._m_has_ior = (self.property_bits & 8) != 0
            return self._m_has_ior if hasattr(self, '_m_has_ior') else None

        @property
        def has_glow(self):
            if hasattr(self, '_m_has_glow'):
                return self._m_has_glow if hasattr(self, '_m_has_glow') else None

            self._m_has_glow = (self.property_bits & 64) != 0
            return self._m_has_glow if hasattr(self, '_m_has_glow') else None


    class Xyzi(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.num_voxels = self._io.read_u4le()
            self.voxels = [None] * (self.num_voxels)
            for i in range(self.num_voxels):
                self.voxels[i] = self._root.Voxel(self._io, self, self._root)



    class Color(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.r = self._io.read_u1()
            self.g = self._io.read_u1()
            self.b = self._io.read_u1()
            self.a = self._io.read_u1()


    class Voxel(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.x = self._io.read_u1()
            self.y = self._io.read_u1()
            self.z = self._io.read_u1()
            self.color_index = self._io.read_u1()