Dice3DS

• Language: Python
• License: BSD-style
• Platform: Windows, Linux, Mac

Dice3DS is a set of Python modules for dealing with 3D Studio format files. I have released it under the terms of a BSD-style license.

3D Studio is a 3D graphics modeling and rendering program that saved it images in a rather simple binary file format known as 3DS format. Although 3D Studio has not released the details of the 3DS format, it has been reverse engineered by some ambitious people, and I used the information to write Dice3DS, a Python package that slices and dices 3DS files.

Dice3DS requires Python 2.6, and numpy 1.1.0. (Earlier versions of Python, going back to 2.2, might still work but are no longer officially supported.) The view3ds script additionally requires any or all of PIL, PyOpenGL 3, PyGame, and Pyglet. PIL and PyOpenGL is enough for most cases.

Examples

Here is an example of creating a 3DS file from scratch, and writing it to output. In the snippet, pointarray is a n-by-3 numpy array listing vertex coordinates, and facearray is an m-by-3 listing of point indices making up a face.

from Dice3DS import dom3ds
import numpy

def output_model(facearray,pointarray,filename):

    n = len(pointarray)
    m = len(facearray)

    # First, add a fourth column to facearray for the face flags.
    # Dice3DS pretty much ignores these flags, but they're required by
    # the 3DS format.

    padfacearray = numpy.zeros((n,4),numpy.uint32)
    padfacearray[:,:3] = facearray
    padfacearray[:,3] = 7

    # Create a smoothing group array.  When the whole model is to be
    # smooth, it is appropriate to set the array to all ones.

    smoothing = numpy.ones(m,numpy.uint32)

    # Create an N_TRI_OBJECT, which is basically a big list of
    # triangles.  This object lists the vertices, faces, smoothing
    # groups, and the transformation matrix, which is set to identity.
    #
    # Note that you can initialize a 3DS chunk in one of two ways: by
    # passing keyword arguments to its constructor, or assigning
    # attributes.

    obj = dom3ds.N_TRI_OBJECT()
    obj.points = dom3ds.POINT_ARRAY(npoints=n,array=pointarray)
    obj.faces = dom3ds.FACE_ARRAY(nfaces=m,array=padfacearray)
    obj.faces.smoothing = dom3ds.SMOOTH_GROUP(array=smoothing)
    obj.matrix = dom3ds.MESH_MATRIX(array=numpy.identity(4,numpy.float32))

    # Create a named object.  Give it the name OBJECT, and set its
    # object to the N_TRI_OBJECT created above.

    nobj = dom3ds.NAMED_OBJECT(name="OBJECT",obj=obj)

    # Now, create the stuff that appears in every (or almost every)
    # 3DS file.

    dom = dom3ds.M3DMAGIC()
    dom.version = dom3ds.M3D_VERSION(number=3)
    dom.mdata = dom3ds.MDATA()
    dom.mdata.scale = dom3ds.MASTER_SCALE(value=1.0)
    dom.mdata.objects = [ nobj ]

    # Output the 3DS file

    dom3ds.write_3ds_file(filename,dom)

Scripts

Dice3DS provides is two scripts, dump3ds and view3ds:

• dump3ds dumps the a 3DS file to output in human-readable form.
• view3ds is a simple 3DS model viewer.

Downloads

Dice3DS is licensed under a BSD-style license.

Version 0.13 is the most recent version, released 5 October 2010.

• ZIP Format
• TGZ Format

If you do Subversion you can get the latest updates here:

• http://www.tamperedevidence.com/repository/dice3ds/trunk/dice3ds

Links

Here are links to the homepages of the libraries used by Dice3DS:

• Numpy
• Python Imaging Library
• PyOpenGL
• PyGame
• Pyglet

Here are some links to other libraries and information about the 3DS file format:

• lib3ds: an LGPLed 3DS file library written in C.
• A description of the 3DS file format

About the name

I originally was going to call it Utility3DS or Util3DS. (Lib3DS was taken, and Py3DS is just lame, as all Py* names are). However, Utility is a boring and aesthetically unpleasing name, and didn’t sound right. (I couldn’t call it 3DSUtil because it needed to be a legal Python symbol.

So, I decided to name it Dice3DS in honor the famous cliche “It slices, it dices!” Definitely cooler and more euphonic than Util3DS.