Contents of a 3D asset package

3D assets are ZIP packages that contain several files necessary for rendering the desired 3D image. These files are:

  • A Material Template Library (MTL) format file.

  • An Object (OBJ) format geometry definition file.

  • Texture files (image format such as JPG, PNG, TIFF, or TGA).

If you download and open the 3D example package, you can see that it contains the following files:

  • canTut14a.mtl: material file

  • canTut14a.obj: model file

  • a_fruitful_uv_map.jpg: texture file

  • aluminum.jpg: texture file

  • can_ring_pull_end_centre.png: texture file

Important

3D rendering does not include subfolders. You must place all your files at the first level of the ZIP package. In addition, you cannot upload the OBJ file alone; you must also upload the MTL file.

MTL file

An MTL file is a material settings file used by 3D object editing applications, such as Adobe Photoshop and Autodesk Maya. It is stored together with an OBJ file and describes how a program applies textures to an object. MTL files contain the names of the texture bitmap files and the 3D coordinates required to apply them to the object.

As shown in the following example, a single .mtl file can define multiple materials. The file defines each material one after the other, starting with the newmtl command.

RequestResponse
# cube.mtl
# Material Count: 1
newmtl Cube
Ns 500
Ka 0.8 0.8 0.8
Kd 0.8 0.8 0.8
Ks 0.8 0.8 0.8
d 1
illum 2
map_Kd aluminum.jpg
Important

If you map to a texture file but omit to place it in the 3D asset, the 3D image does not render.

OBJ file

The OBJ file format is a simple data format that represents 3D geometry.

Object files must be in ASCII format (.obj). Sitecore Content Hub does not support object files in a binary format (.mod).

You can include the following data types in an .obj file:

  • Geometric vertices (v)

  • Texture vertices (vt)

  • Vertex normals (vn)

  • Parameter space vertices (vp)

  • Free-form curve/surface attributes

  • Rational or non-rational forms of curve or surface type:

    • Basis matrix

    • Bezier

    • B-spline

    • Cardinal, Taylor (cstype)

  • Degree (deg)

  • Basis matrix (bmat)

  • Step size (step)

  • Point (p)

  • Line (l)

  • Face (f)

  • Curve (curv)

  • 2D curve (curv2)

  • Surface (surf)

  • Parameter values (parm)

  • Outer trimming loop (trim)

  • Inner trimming loop (hole)

  • Special curve (scrv)

  • Special point (sp)

  • End statement (end)

  • Connect (con)

  • Group name (g)

  • Smoothing group (s)

  • Merging group (mg)- object name *(o)

  • Bevel interpolation

  • Color interpolation (c_interp)

  • Dissolve interpolation (d_interp)

  • Level of detail (lod)

  • Material name (usemtl)

  • Material library (mtllib)

  • Shadow casting (shadow_obj)

  • Ray tracing (trace_obj)

  • Curve approximation technique (ctech)

  • Surface approximation technique (stech)

In the following example, the .obj file references the cube.mtl file.

RequestResponse
# cube.obj 
#referencing cube.mtl
mtllib cube.mtl
o 3D_model_of_a_Cube
v 0.000000 0.000000 -30.000000
v 0.000000 30.000000 0.000000
v 0.000000 30.000000 -30.000000
v 0.000000 0.000000 0.000000
v 30.000000 30.000000 0.000000
v 30.000000 0.000000 -30.000000
v 30.000000 30.000000 -30.000000
v 30.000000 0.000000 0.000000
vn -1.0000 0.0000 0.0000
vn 1.0000 0.0000 0.0000
vn 0.0000 0.0000 1.0000
vn 0.0000 0.0000 -1.0000
vn 0.0000 -1.0000 0.0000
vn 0.0000 1.0000 0.0000
g 3D_model_of_a_Cube_3D_model_of_a_Cube_None
usemtl Cube
s off
f 1//1 2//1 3//1
f 4//1 2//1 1//1
f 5//2 6//2 7//2
f 5//2 8//2 6//2
f 8//3 5//3 4//3
f 4//3 5//3 2//3
f 7//4 6//4 1//4
f 7//4 1//4 3//4
f 1//5 6//5 4//5
f 4//5 6//5 8//5
f 7//6 3//6 2//6
f 7//6 2//6 5//6

Mapping multi-materials to 3D assets

Content Hub does not support mapping multi-materials to 3D assets. For example, if you have a 3D cube with six faces, and the .mtl file includes six materials (one mapping to each face), then the cube renders. However, if your .mtl file includes twelve materials and maps two to each face, the rendition shows a transparent cube without any filling materials.

3D model with multi-materials mapping

3D asset rendering in Content Hub

3d model rendered with multi-materials mapping
3d model with multi-materials mapping rendered transparent in Content Hub

Texture files

Textures are images mapped to the surface of your 3D asset. You place the texture files in the same folder as the MTL and OBJ files. If your textures are correctly referenced, your 3D image renders automatically.

Do you have some feedback for us?

If you have suggestions for improving this article,