ms3d_spec.py

# ##### BEGIN GPL LICENSE BLOCK #####
#
#  This program is free software; you can redistribute it and/or
#  modify it under the terms of the GNU General Public License
#  as published by the Free Software Foundation; either version 2
#  of the License, or (at your option) any later version.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#
#  You should have received a copy of the GNU General Public License
#  along with this program; if not, write to the Free Software Foundation,
#  Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
#
# ##### END GPL LICENSE BLOCK #####

# <pep8 compliant>

###############################################################################
#234567890123456789012345678901234567890123456789012345678901234567890123456789
#--------1---------2---------3---------4---------5---------6---------7---------


# ##### BEGIN COPYRIGHT BLOCK #####
#
# initial script copyright (c)2011,2012 Alexander Nussbaumer
#
# ##### END COPYRIGHT BLOCK #####


from struct import (
        pack,
        unpack,
        )
from sys import (
        exc_info,
        )
from codecs import (
        register_error,
        )

###############################################################################
#
# MilkShape 3D 1.8.5 File Format Specification
#
# all specifications were taken from SDK 1.8.5
#
# some additional specifications were taken from
# MilkShape 3D Viewer v2.0 (Nov 06 2007) - msMesh.h
#


###############################################################################
#
# sizes
#

class Ms3dSpec:
    ###########################################################################
    #
    # max values
    #
    MAX_VERTICES = 65534 # 0..65533; note: (65534???, 65535???)
    MAX_TRIANGLES = 65534 # 0..65533; note: (65534???, 65535???)
    MAX_GROUPS = 255 # 1..255; note: (0 default group)
    MAX_MATERIALS = 128 # 0..127; note: (-1 no material)
    MAX_JOINTS = 128 # 0..127; note: (-1 no joint)
    MAX_SMOOTH_GROUP = 32 # 0..32; note: (0 no smoothing group)
    MAX_TEXTURE_FILENAME_SIZE = 128

    ###########################################################################
    #
    # flags
    #
    FLAG_NONE = 0
    FLAG_SELECTED = 1
    FLAG_HIDDEN = 2
    FLAG_SELECTED2 = 4
    FLAG_DIRTY = 8
    FLAG_ISKEY = 16 # additional spec from [2]
    FLAG_NEWLYCREATED = 32 # additional spec from [2]
    FLAG_MARKED = 64 # additional spec from [2]

    FLAG_TEXTURE_NONE = 0x00
    FLAG_TEXTURE_COMBINE_ALPHA = 0x20
    FLAG_TEXTURE_HAS_ALPHA = 0x40
    FLAG_TEXTURE_SPHERE_MAP = 0x80

    MODE_TRANSPARENCY_SIMPLE = 0
    MODE_TRANSPARENCY_DEPTH_BUFFERED_WITH_ALPHA_REF = 1
    MODE_TRANSPARENCY_DEPTH_SORTED_TRIANGLES = 2


    ###########################################################################
    #
    # values
    #
    HEADER = "MS3D000000"


    ## TEST_STR = 'START@€@µ@²@³@©@®@¶@ÿ@A@END.bmp'
    ## TEST_RAW = b'START@\x80@\xb5@\xb2@\xb3@\xa9@\xae@\xb6@\xff@A@END.bmp\x00'
    ##
    STRING_MS3D_REPLACE = 'use_ms3d_replace'
    STRING_ENCODING = "ascii" # wrong encoding (too limited), but there is an UnicodeEncodeError issue, that prevent using the correct one for the moment
    ##STRING_ENCODING = "cp437" # US, wrong encoding and shows UnicodeEncodeError
    ##STRING_ENCODING = "cp858" # Europe + €, wrong encoding and shows UnicodeEncodeError
    ##STRING_ENCODING = "cp1252" # WIN EU, this would be the better codepage, but shows UnicodeEncodeError, on print on system console and writing to file
    STRING_ERROR = STRING_MS3D_REPLACE
    ##STRING_ERROR = 'replace'
    ##STRING_ERROR = 'ignore'
    ##STRING_ERROR = 'surrogateescape'
    STRING_TERMINATION = b'\x00'
    STRING_REPLACE = u'_'


    ###########################################################################
    #
    # min, max, default values
    #
    NONE_VERTEX_BONE_ID = -1
    NONE_GROUP_MATERIAL_INDEX = -1

    DEFAULT_HEADER = HEADER
    DEFAULT_HEADER_VERSION = 4
    DEFAULT_VERTEX_BONE_ID = NONE_VERTEX_BONE_ID
    DEFAULT_TRIANGLE_SMOOTHING_GROUP = 0
    DEFAULT_TRIANGLE_GROUP = 0
    DEFAULT_MATERIAL_MODE = FLAG_TEXTURE_NONE
    DEFAULT_GROUP_MATERIAL_INDEX = NONE_GROUP_MATERIAL_INDEX
    DEFAULT_MODEL_JOINT_SIZE = 1.0
    DEFAULT_MODEL_TRANSPARENCY_MODE = MODE_TRANSPARENCY_SIMPLE
    DEFAULT_MODEL_ANIMATION_FPS = 25.0
    DEFAULT_MODEL_SUB_VERSION_COMMENTS = 1
    DEFAULT_MODEL_SUB_VERSION_VERTEX_EXTRA = 2
    DEFAULT_MODEL_SUB_VERSION_JOINT_EXTRA = 1
    DEFAULT_MODEL_SUB_VERSION_MODEL_EXTRA = 1
    DEFAULT_FLAGS = FLAG_NONE
    MAX_MATERIAL_SHININESS = 128

    # blender default / OpenGL default
    DEFAULT_MATERIAL_AMBIENT = (0.2, 0.2, 0.2, 1.0)
    DEFAULT_MATERIAL_DIFFUSE = (0.8, 0.8, 0.8, 1.0)
    DEFAULT_MATERIAL_SPECULAR = (1.0, 1.0, 1.0, 1.0)
    DEFAULT_MATERIAL_EMISSIVE = (0.0, 0.0, 0.0, 1.0)
    DEFAULT_MATERIAL_SHININESS = 12.5

    DEFAULT_JOINT_COLOR = (0.8, 0.8, 0.8)

###############################################################################
#
# helper class for basic raw io
#
class Ms3dIo:
    # sizes for IO
    SIZE_BYTE = 1
    SIZE_SBYTE = 1
    SIZE_WORD = 2
    SIZE_DWORD = 4
    SIZE_FLOAT = 4
    LENGTH_ID = 10
    LENGTH_NAME = 32
    LENGTH_FILENAME = 128

    PRECISION = 4

    @staticmethod
    def read_byte(raw_io):
        """ read a single byte from raw_io """
        buffer = raw_io.read(Ms3dIo.SIZE_BYTE)
        if not buffer:
            raise EOFError()
        value = unpack('<B', buffer)[0]
        return value

    @staticmethod
    def write_byte(raw_io, value):
        """ write a single byte to raw_io """
        raw_io.write(pack('<B', value))

    @staticmethod
    def read_sbyte(raw_io):
        """ read a single signed byte from raw_io """
        buffer = raw_io.read(Ms3dIo.SIZE_BYTE)
        if not buffer:
            raise EOFError()
        value = unpack('<b', buffer)[0]
        return value

    @staticmethod
    def write_sbyte(raw_io, value):
        """ write a single signed byte to raw_io """
        raw_io.write(pack('<b', value))

    @staticmethod
    def read_word(raw_io):
        """ read a word from raw_io """
        buffer = raw_io.read(Ms3dIo.SIZE_WORD)
        if not buffer:
            raise EOFError()
        value = unpack('<H', buffer)[0]
        return value

    @staticmethod
    def write_word(raw_io, value):
        """ write a word to raw_io """
        raw_io.write(pack('<H', value))

    @staticmethod
    def read_dword(raw_io):
        """ read a double word from raw_io """
        buffer = raw_io.read(Ms3dIo.SIZE_DWORD)
        if not buffer:
            raise EOFError()
        value = unpack('<I', buffer)[0]
        return value

    @staticmethod
    def write_dword(raw_io, value):
        """ write a double word to raw_io """
        raw_io.write(pack('<I', value))

    @staticmethod
    def read_float(raw_io):
        """ read a float from raw_io """
        buffer = raw_io.read(Ms3dIo.SIZE_FLOAT)
        if not buffer:
            raise EOFError()
        value = unpack('<f', buffer)[0]
        return value

    @staticmethod
    def write_float(raw_io, value):
        """ write a float to raw_io """
        raw_io.write(pack('<f', value))

    @staticmethod
    def read_array(raw_io, itemReader, count):
        """ read an array[count] of objects from raw_io, by using a itemReader """
        value = []
        for i in range(count):
            itemValue = itemReader(raw_io)
            value.append(itemValue)
        return tuple(value)

    @staticmethod
    def write_array(raw_io, itemWriter, count, value):
        """ write an array[count] of objects to raw_io, by using a itemWriter """
        for i in range(count):
            itemValue = value[i]
            itemWriter(raw_io, itemValue)

    @staticmethod
    def read_array2(raw_io, itemReader, count, count2):
        """ read an array[count][count2] of objects from raw_io,
            by using a itemReader """
        value = []
        for i in range(count):
            itemValue = Ms3dIo.read_array(raw_io, itemReader, count2)
            value.append(tuple(itemValue))
        return value

    @staticmethod
    def write_array2(raw_io, itemWriter, count, count2, value):
        """ write an array[count][count2] of objects to raw_io,
            by using a itemWriter """
        for i in range(count):
            itemValue = value[i]
            Ms3dIo.write_array(raw_io, itemWriter, count2, itemValue)


    @staticmethod
    def ms3d_replace(exc):
        """ http://www.python.org/dev/peps/pep-0293/ """
        if isinstance(exc, UnicodeEncodeError):
            return ((exc.end-exc.start)*Ms3dSpec.STRING_REPLACE, exc.end)
        elif isinstance(exc, UnicodeDecodeError):
            return (Ms3dSpec.STRING_REPLACE, exc.end)
        elif isinstance(exc, UnicodeTranslateError):
            return ((exc.end-exc.start)*Ms3dSpec.STRING_REPLACE, exc.end)
        else:
            raise TypeError("can't handle %s" % exc.__name__)

    @staticmethod
    def read_string(raw_io, length):
        """ read a string of a specific length from raw_io """
        buffer = raw_io.read(length)
        if not buffer:
            raise EOFError()
        eol = buffer.find(Ms3dSpec.STRING_TERMINATION)
        register_error(Ms3dSpec.STRING_MS3D_REPLACE, Ms3dIo.ms3d_replace)
        s = buffer[:eol].decode(encoding=Ms3dSpec.STRING_ENCODING, errors=Ms3dSpec.STRING_ERROR)
        return s

    @staticmethod
    def write_string(raw_io, length, value):
        """ write a string of a specific length to raw_io """
        register_error(Ms3dSpec.STRING_MS3D_REPLACE, Ms3dIo.ms3d_replace)
        buffer = value.encode(encoding=Ms3dSpec.STRING_ENCODING, errors=Ms3dSpec.STRING_ERROR)
        if not buffer:
            buffer = bytes()
        raw_io.write(pack('<{}s'.format(length), buffer))
        return


###############################################################################
#
# multi complex types
#

###############################################################################
class Ms3dHeader:
    """ Ms3dHeader """
    __slots__ = (
            'id',
            'version',
            )

    def __init__(
            self,
            default_id=Ms3dSpec.DEFAULT_HEADER,
            default_version=Ms3dSpec.DEFAULT_HEADER_VERSION
            ):
        self.id = default_id
        self.version = default_version

    def __repr__(self):
        return "\n<id='{}', version={}>".format(
            self.id,
            self.version
            )

    def __hash__(self):
        return hash(self.id) ^ hash(self.version)

    def __eq__(self, other):
        return ((self is not None) and (other is not None)
                and (self.id == other.id)
                and (self.version == other.version))

    def read(self, raw_io):
        self.id = Ms3dIo.read_string(raw_io, Ms3dIo.LENGTH_ID)
        self.version = Ms3dIo.read_dword(raw_io)
        return self

    def write(self, raw_io):
        Ms3dIo.write_string(raw_io, Ms3dIo.LENGTH_ID, self.id)
        Ms3dIo.write_dword(raw_io, self.version)


###############################################################################
class Ms3dVertex:
    """ Ms3dVertex """
    """
    __slots__ was taking out,
    to be able to inject additional attributes during runtime
    __slots__ = (
            'flags',
            'bone_id',
            'reference_count',
            '_vertex',
            '_vertex_ex_object', # Ms3dVertexEx
            )
    """

    def __init__(
            self,
            default_flags=Ms3dSpec.DEFAULT_FLAGS,
            default_vertex=(0.0, 0.0, 0.0),
            default_bone_id=Ms3dSpec.DEFAULT_VERTEX_BONE_ID,
            default_reference_count=0,
            default_vertex_ex_object=None, # Ms3dVertexEx
            ):
        self.flags = default_flags
        self._vertex = default_vertex
        self.bone_id = default_bone_id
        self.reference_count = default_reference_count

        if default_vertex_ex_object is None:
            default_vertex_ex_object = Ms3dVertexEx2()
            # Ms3dSpec.DEFAULT_MODEL_SUB_VERSION_VERTEX_EXTRA = 2
        self._vertex_ex_object = default_vertex_ex_object
        # Ms3dVertexEx

    def __repr__(self):
        return "\n<flags={}, vertex=({:.{p}f}, {:.{p}f}, {:.{p}f}), bone_id={},"\
                " reference_count={}>".format(
                self.flags,
                self._vertex[0],
                self._vertex[1],
                self._vertex[2],
                self.bone_id,
                self.reference_count,
                p=Ms3dIo.PRECISION
                )

    def __hash__(self):
        return (hash(self.vertex)
                #^ hash(self.flags)
                #^ hash(self.bone_id)
                #^ hash(self.reference_count)
                )

    def __eq__(self, other):
        return ((self.vertex == other.vertex)
                #and (self.flags == other.flags)
                #and (self.bone_id == other.bone_id)
                #and (self.reference_count == other.reference_count)
                )


    @property
    def vertex(self):
        return self._vertex

    @property
    def vertex_ex_object(self):
        return self._vertex_ex_object


    def read(self, raw_io):
        self.flags = Ms3dIo.read_byte(raw_io)
        self._vertex = Ms3dIo.read_array(raw_io, Ms3dIo.read_float, 3)
        self.bone_id = Ms3dIo.read_sbyte(raw_io)
        self.reference_count = Ms3dIo.read_byte(raw_io)
        return self

    def write(self, raw_io):
        Ms3dIo.write_byte(raw_io, self.flags)
        Ms3dIo.write_array(raw_io, Ms3dIo.write_float, 3, self.vertex)
        Ms3dIo.write_sbyte(raw_io, self.bone_id)
        Ms3dIo.write_byte(raw_io, self.reference_count)


###############################################################################
class Ms3dTriangle:
    """ Ms3dTriangle """
    """
    __slots__ was taking out,
    to be able to inject additional attributes during runtime
    __slots__ = (
            'flags',
            'smoothing_group',
            'group_index',
            '_vertex_indices',
            '_vertex_normals',
            '_s',
            '_t',
            )
    """

    def __init__(
            self,
            default_flags=Ms3dSpec.DEFAULT_FLAGS,
            default_vertex_indices=(0, 0, 0),
            default_vertex_normals=(
                    (0.0, 0.0, 0.0),
                    (0.0, 0.0, 0.0),
                    (0.0, 0.0, 0.0)),
            default_s=(0.0, 0.0, 0.0),
            default_t=(0.0, 0.0, 0.0),
            default_smoothing_group=Ms3dSpec.DEFAULT_TRIANGLE_SMOOTHING_GROUP,
            default_group_index=Ms3dSpec.DEFAULT_TRIANGLE_GROUP
            ):
        self.flags = default_flags
        self._vertex_indices = default_vertex_indices
        self._vertex_normals = default_vertex_normals
        self._s = default_s
        self._t = default_t
        self.smoothing_group = default_smoothing_group
        self.group_index = default_group_index

    def __repr__(self):
        return "\n<flags={}, vertex_indices={}, vertex_normals=(({:.{p}f}, "\
                "{:.{p}f}, {:.{p}f}), ({:.{p}f}, {:.{p}f}, {:.{p}f}), ({:.{p}f}, "\
                "{:.{p}f}, {:.{p}f})), s=({:.{p}f}, {:.{p}f}, {:.{p}f}), "\
                "t=({:.{p}f}, {:.{p}f}, {:.{p}f}), smoothing_group={}, "\
                "group_index={}>".format(
                self.flags,
                self.vertex_indices,
                self.vertex_normals[0][0],
                self.vertex_normals[0][1],
                self.vertex_normals[0][2],
                self.vertex_normals[1][0],
                self.vertex_normals[1][1],
                self.vertex_normals[1][2],
                self.vertex_normals[2][0],
                self.vertex_normals[2][1],
                self.vertex_normals[2][2],
                self.s[0],
                self.s[1],
                self.s[2],
                self.t[0],
                self.t[1],
                self.t[2],
                self.smoothing_group,
                self.group_index,
                p=Ms3dIo.PRECISION
                )


    @property
    def vertex_indices(self):
        return self._vertex_indices

    @property
    def vertex_normals(self):
        return self._vertex_normals

    @property
    def s(self):
        return self._s

    @property
    def t(self):
        return self._t


    def read(self, raw_io):
        self.flags = Ms3dIo.read_word(raw_io)
        self._vertex_indices = Ms3dIo.read_array(raw_io, Ms3dIo.read_word, 3)
        self._vertex_normals = Ms3dIo.read_array2(raw_io, Ms3dIo.read_float, 3, 3)
        self._s = Ms3dIo.read_array(raw_io, Ms3dIo.read_float, 3)
        self._t = Ms3dIo.read_array(raw_io, Ms3dIo.read_float, 3)
        self.smoothing_group = Ms3dIo.read_byte(raw_io)
        self.group_index = Ms3dIo.read_byte(raw_io)
        return self

    def write(self, raw_io):
        Ms3dIo.write_word(raw_io, self.flags)
        Ms3dIo.write_array(raw_io, Ms3dIo.write_word, 3, self.vertex_indices)
        Ms3dIo.write_array2(raw_io, Ms3dIo.write_float, 3, 3, self.vertex_normals)
        Ms3dIo.write_array(raw_io, Ms3dIo.write_float, 3, self.s)
        Ms3dIo.write_array(raw_io, Ms3dIo.write_float, 3, self.t)
        Ms3dIo.write_byte(raw_io, self.smoothing_group)
        Ms3dIo.write_byte(raw_io, self.group_index)


###############################################################################
class Ms3dGroup:
    """ Ms3dGroup """
    """
    __slots__ was taking out,
    to be able to inject additional attributes during runtime
    __slots__ = (
            'flags',
            'name',
            'material_index',
            '_triangle_indices',
            '_comment_object', # Ms3dComment
            )
    """

    def __init__(
            self,
            default_flags=Ms3dSpec.DEFAULT_FLAGS,
            default_name="",
            default_triangle_indices=None,
            default_material_index=Ms3dSpec.DEFAULT_GROUP_MATERIAL_INDEX,
            default_comment_object=None, # Ms3dComment
            ):
        if (default_name is None):
            default_name = ""

        if (default_triangle_indices is None):
            default_triangle_indices = []

        self.flags = default_flags
        self.name = default_name
        self._triangle_indices = default_triangle_indices
        self.material_index = default_material_index

        if default_comment_object is None:
            default_comment_object = Ms3dCommentEx()
        self._comment_object = default_comment_object # Ms3dComment

    def __repr__(self):
        return "\n<flags={}, name='{}', number_triangles={},"\
                " triangle_indices={}, material_index={}>".format(
                self.flags,
                self.name,
                self.number_triangles,
                self.triangle_indices,
                self.material_index
                )


    @property
    def number_triangles(self):
        if self.triangle_indices is None:
            return 0
        return len(self.triangle_indices)

    @property
    def triangle_indices(self):
        return self._triangle_indices

    @property
    def comment_object(self):
        return self._comment_object


    def read(self, raw_io):
        self.flags = Ms3dIo.read_byte(raw_io)
        self.name = Ms3dIo.read_string(raw_io, Ms3dIo.LENGTH_NAME)
        _number_triangles = Ms3dIo.read_word(raw_io)
        self._triangle_indices = Ms3dIo.read_array(
                raw_io, Ms3dIo.read_word, _number_triangles)
        self.material_index = Ms3dIo.read_sbyte(raw_io)
        return self

    def write(self, raw_io):
        Ms3dIo.write_byte(raw_io, self.flags)
        Ms3dIo.write_string(raw_io, Ms3dIo.LENGTH_NAME, self.name)
        Ms3dIo.write_word(raw_io, self.number_triangles)
        Ms3dIo.write_array(
                raw_io, Ms3dIo.write_word, self.number_triangles,
                self.triangle_indices)
        Ms3dIo.write_sbyte(raw_io, self.material_index)


###############################################################################
class Ms3dMaterial:
    """ Ms3dMaterial """
    """
    __slots__ was taking out,
    to be able to inject additional attributes during runtime
    __slots__ = (
            'name',
            'shininess',
            'transparency',
            'mode',
            'texture',
            'alphamap',
            '_ambient',
            '_diffuse',
            '_specular',
            '_emissive',
            '_comment_object', # Ms3dComment
            )
    """

    def __init__(
            self,
            default_name="",
            default_ambient=list(Ms3dSpec.DEFAULT_MATERIAL_AMBIENT),
            default_diffuse=list(Ms3dSpec.DEFAULT_MATERIAL_DIFFUSE),
            default_specular=list(Ms3dSpec.DEFAULT_MATERIAL_SPECULAR),
            default_emissive=list(Ms3dSpec.DEFAULT_MATERIAL_EMISSIVE),
            default_shininess=Ms3dSpec.DEFAULT_MATERIAL_SHININESS,
            default_transparency=0.0,
            default_mode=Ms3dSpec.DEFAULT_MATERIAL_MODE,
            default_texture="",
            default_alphamap="",
            default_comment_object=None, # Ms3dComment
            ):
        if (default_name is None):
            default_name = ""

        if (default_texture is None):
            default_texture = ""

        if (default_alphamap is None):
            default_alphamap = ""

        self.name = default_name
        self._ambient = default_ambient
        self._diffuse = default_diffuse
        self._specular = default_specular
        self._emissive = default_emissive
        self.shininess = default_shininess
        self.transparency = default_transparency
        self.mode = default_mode
        self.texture = default_texture
        self.alphamap = default_alphamap

        if default_comment_object is None:
            default_comment_object = Ms3dCommentEx()
        self._comment_object = default_comment_object # Ms3dComment

    def __repr__(self):
        return "\n<name='{}', ambient=({:.{p}f}, {:.{p}f}, {:.{p}f}, {:.{p}f}), "\
                "diffuse=({:.{p}f}, {:.{p}f}, {:.{p}f}, {:.{p}f}), specular=("\
                "{:.{p}f}, {:.{p}f}, {:.{p}f}, {:.{p}f}), emissive=({:.{p}f}, "\
                "{:.{p}f}, {:.{p}f}, {:.{p}f}), shininess={:.{p}f}, transparency="\
                "{:.{p}f}, mode={}, texture='{}', alphamap='{}'>".format(
                self.name,
                self.ambient[0],
                self.ambient[1],
                self.ambient[2],
                self.ambient[3],
                self.diffuse[0],
                self.diffuse[1],
                self.diffuse[2],
                self.diffuse[3],
                self.specular[0],
                self.specular[1],
                self.specular[2],
                self.specular[3],
                self.emissive[0],
                self.emissive[1],
                self.emissive[2],
                self.emissive[3],
                self.shininess,
                self.transparency,
                self.mode,
                self.texture,
                self.alphamap,
                p=Ms3dIo.PRECISION
                )

    def __hash__(self):
        return (hash(self.name)

                ^ hash(self.ambient)
                ^ hash(self.diffuse)
                ^ hash(self.specular)
                ^ hash(self.emissive)

                ^ hash(self.shininess)
                ^ hash(self.transparency)
                ^ hash(self.mode)

                ^ hash(self.texture)
                ^ hash(self.alphamap)
                )

    def __eq__(self, other):
        return ((self.name == other.name)

                and (self.ambient == other.ambient)
                and (self.diffuse == other.diffuse)
                and (self.specular == other.specular)
                and (self.emissive == other.emissive)

                and (self.shininess == other.shininess)
                and (self.transparency == other.transparency)
                and (self.mode == other.mode)

                #and (self.texture == other.texture)
                #and (self.alphamap == other.alphamap)
                )


    @property
    def ambient(self):
        return self._ambient

    @property
    def diffuse(self):
        return self._diffuse

    @property
    def specular(self):
        return self._specular

    @property
    def emissive(self):
        return self._emissive

    @property
    def comment_object(self):
        return self._comment_object


    def read(self, raw_io):
        self.name = Ms3dIo.read_string(raw_io, Ms3dIo.LENGTH_NAME)
        self._ambient = Ms3dIo.read_array(raw_io, Ms3dIo.read_float, 4)
        self._diffuse = Ms3dIo.read_array(raw_io, Ms3dIo.read_float, 4)
        self._specular = Ms3dIo.read_array(raw_io, Ms3dIo.read_float, 4)
        self._emissive = Ms3dIo.read_array(raw_io, Ms3dIo.read_float, 4)
        self.shininess = Ms3dIo.read_float(raw_io)
        self.transparency = Ms3dIo.read_float(raw_io)
        self.mode = Ms3dIo.read_byte(raw_io)
        self.texture = Ms3dIo.read_string(raw_io, Ms3dIo.LENGTH_FILENAME)
        self.alphamap = Ms3dIo.read_string(raw_io, Ms3dIo.LENGTH_FILENAME)
        return self

    def write(self, raw_io):
        Ms3dIo.write_string(raw_io, Ms3dIo.LENGTH_NAME, self.name)
        Ms3dIo.write_array(raw_io, Ms3dIo.write_float, 4, self.ambient)
        Ms3dIo.write_array(raw_io, Ms3dIo.write_float, 4, self.diffuse)
        Ms3dIo.write_array(raw_io, Ms3dIo.write_float, 4, self.specular)
        Ms3dIo.write_array(raw_io, Ms3dIo.write_float, 4, self.emissive)
        Ms3dIo.write_float(raw_io, self.shininess)
        Ms3dIo.write_float(raw_io, self.transparency)
        Ms3dIo.write_byte(raw_io, self.mode)
        Ms3dIo.write_string(raw_io, Ms3dIo.LENGTH_FILENAME, self.texture)
        Ms3dIo.write_string(raw_io, Ms3dIo.LENGTH_FILENAME, self.alphamap)


###############################################################################
class Ms3dRotationKeyframe:
    """ Ms3dRotationKeyframe """
    __slots__ = (
            'time',
            '_rotation',
            )

    def __init__(
            self,
            default_time=0.0,
            default_rotation=(0.0, 0.0, 0.0)
            ):
        self.time = default_time
        self._rotation = default_rotation

    def __repr__(self):
        return "\n<time={:.{p}f}, rotation=({:.{p}f}, {:.{p}f}, {:.{p}f})>".format(
                self.time,
                self.rotation[0],
                self.rotation[1],
                self.rotation[2],
                p=Ms3dIo.PRECISION
                )


    @property
    def rotation(self):
        return self._rotation


    def read(self, raw_io):
        self.time = Ms3dIo.read_float(raw_io)
        self._rotation = Ms3dIo.read_array(raw_io, Ms3dIo.read_float, 3)
        return self

    def write(self, raw_io):
        Ms3dIo.write_float(raw_io, self.time)
        Ms3dIo.write_array(raw_io, Ms3dIo.write_float, 3, self.rotation)


###############################################################################
class Ms3dTranslationKeyframe:
    """ Ms3dTranslationKeyframe """
    __slots__ = (
            'time',
            '_position',
            )

    def __init__(
            self,
            default_time=0.0,
            default_position=(0.0, 0.0, 0.0)
            ):
        self.time = default_time
        self._position = default_position

    def __repr__(self):
        return "\n<time={:.{p}f}, position=({:.{p}f}, {:.{p}f}, {:.{p}f})>".format(
                self.time,
                self.position[0],
                self.position[1],
                self.position[2],
                p=Ms3dIo.PRECISION
                )


    @property
    def position(self):
        return self._position


    def read(self, raw_io):
        self.time = Ms3dIo.read_float(raw_io)
        self._position = Ms3dIo.read_array(raw_io, Ms3dIo.read_float, 3)
        return self

    def write(self, raw_io):
        Ms3dIo.write_float(raw_io, self.time)
        Ms3dIo.write_array(raw_io, Ms3dIo.write_float, 3, self.position)


###############################################################################
class Ms3dJoint:
    """ Ms3dJoint """
    """
    __slots__ was taking out,
    to be able to inject additional attributes during runtime
    __slots__ = (
            'flags',
            'name',
            'parent_name',
            '_rotation',
            '_position',
            '_rotation_keyframes',
            '_translation_keyframes',
            '_joint_ex_object', # Ms3dJointEx
            '_comment_object', # Ms3dComment
            )
    """

    def __init__(
            self,
            default_flags=Ms3dSpec.DEFAULT_FLAGS,
            default_name="",
            default_parent_name="",
            default_rotation=(0.0, 0.0, 0.0),
            default_position=(0.0, 0.0, 0.0),
            default_rotation_keyframes=None,
            default_translation_keyframes=None,
            default_joint_ex_object=None, # Ms3dJointEx
            default_comment_object=None, # Ms3dComment
            ):
        if (default_name is None):
            default_name = ""

        if (default_parent_name is None):
            default_parent_name = ""

        if (default_rotation_keyframes is None):
            default_rotation_keyframes = [] #Ms3dRotationKeyframe()

        if (default_translation_keyframes is None):
            default_translation_keyframes = [] #Ms3dTranslationKeyframe()

        self.flags = default_flags
        self.name = default_name
        self.parent_name = default_parent_name
        self._rotation = default_rotation
        self._position = default_position
        self._rotation_keyframes = default_rotation_keyframes
        self._translation_keyframes = default_translation_keyframes

        if default_comment_object is None:
            default_comment_object = Ms3dCommentEx()
        self._comment_object = default_comment_object # Ms3dComment

        if default_joint_ex_object is None:
            default_joint_ex_object = Ms3dJointEx()
        self._joint_ex_object = default_joint_ex_object # Ms3dJointEx

    def __repr__(self):
        return "\n<flags={}, name='{}', parent_name='{}', rotation=({:.{p}f}, "\
                "{:.{p}f}, {:.{p}f}), position=({:.{p}f}, {:.{p}f}, {:.{p}f}), "\
                "number_rotation_keyframes={}, number_translation_keyframes={},"\
                " rotation_key_frames={}, translation_key_frames={}>".format(
                self.flags,
                self.name,
                self.parent_name,
                self.rotation[0],
                self.rotation[1],
                self.rotation[2],
                self.position[0],
                self.position[1],
                self.position[2],
                self.number_rotation_keyframes,
                self.number_translation_keyframes,
                self.rotation_key_frames,
                self.translation_key_frames,
                p=Ms3dIo.PRECISION
                )


    @property
    def rotation(self):
        return self._rotation

    @property
    def position(self):
        return self._position

    @property
    def number_rotation_keyframes(self):
        if self.rotation_key_frames is None:
            return 0
        return len(self.rotation_key_frames)

    @property
    def number_translation_keyframes(self):
        if self.translation_key_frames is None:
            return 0
        return len(self.translation_key_frames)

    @property
    def rotation_key_frames(self):
        return self._rotation_keyframes

    @property
    def translation_key_frames(self):
        return self._translation_keyframes


    @property
    def joint_ex_object(self):
        return self._joint_ex_object


    @property
    def comment_object(self):
        return self._comment_object


    def read(self, raw_io):
        self.flags = Ms3dIo.read_byte(raw_io)
        self.name = Ms3dIo.read_string(raw_io, Ms3dIo.LENGTH_NAME)
        self.parent_name = Ms3dIo.read_string(raw_io, Ms3dIo.LENGTH_NAME)
        self._rotation = Ms3dIo.read_array(raw_io, Ms3dIo.read_float, 3)