usemtl

Usemtl is a directive in the Wavefront OBJ file format used to assign a material to subsequent polygonal faces. It relies on a material library defined in a separate MTL file, loaded by the mtllib directive. Materials in an MTL file are declared with newmtl and defined with properties such as Ka (ambient color), Kd (diffuse color), Ks (specular color), Ns (shininess), Ni (optical density), d (opacity), and illum (illumination model). Texture maps may be specified with map_Kd, map_Ks, and other map parameters.

When a model is read, the usemtl line selects the active material by name. All faces following that line use that material until another usemtl line is encountered or the file ends. This enables per-face or per-group material variation by inserting multiple usemtl statements at appropriate points.

Syntax example:

mtllib materials.mtl

usemtl Gold

In the OBJ workflow, materials are optional; if no usemtl is specified, faces render with no material or a default material, depending on the software. If a referenced material name in usemtl does not appear in the loaded MTL, the material will be undefined for those faces, potentially causing rendering issues.

Software compatibility: usemtl is widely supported by OBJ readers and 3D software, though some programs may implement variations or require strict ordering (mtllib before usemtl). It remains a core mechanism for assigning and switching materials within OBJ models.