H073.HxOBJ 1.0.0

HxOBJ — Wavefront OBJ/MTL Parser for .NET

HxOBJ is a fast, feature-complete library for loading Wavefront OBJ and MTL files into structured C# objects.

Features

• Full OBJ Specification — Vertices, normals, texture coordinates, faces, groups, objects, smoothing groups
• N-gon Support — Triangles, quads, and arbitrary polygons
• Vertex Colors — Extended v x y z r g b format
• MTL Materials — Diffuse, ambient, specular, emissive, PBR extensions (roughness, metallic, sheen, clearcoat)
• Texture Maps — Diffuse, normal/bump, emissive, metallic/roughness with offset/scale/turbulence
• Async Loading — ObjReader.ReadAsync() with cancellation
• Free-Form Geometry — NURBS curves and surfaces (optional)
• Span-Based Parsing — Zero-allocation tokenization, string interning, pre-allocated buffers

Installation

dotnet add package H073.HxOBJ

<PackageReference Include="H073.HxOBJ" Version="1.0.0" />

Quick Start

using HxOBJ;

// Load (automatically loads referenced MTL files)
var obj = ObjReader.Read("model.obj");

// With options
var obj = ObjReader.Read("model.obj", new ObjReadOptions { SkipFreeForm = true });

// Async
var obj = await ObjReader.ReadAsync("model.obj");

// Access geometry
foreach (var face in obj.Faces)
{
    foreach (ref var fv in face.Vertices.AsSpan())
    {
        var position = obj.Vertices[fv.VertexIndex].Position;
        // fv.NormalIndex, fv.TexCoordIndex (-1 if absent)
    }
}

// Access materials
foreach (var (name, mat) in obj.Materials)
{
    var diffuse = mat.Kd;        // ObjColor?
    var roughness = mat.Pr;      // float?
    var diffuseMap = mat.MapKd;  // ObjTextureMap?
}

Data Structure

ObjFile
├── Vertices[]       — Position, W, Color
├── Normals[]        — Vector3
├── TexCoords[]      — Vector3 (UVW)
├── Faces[]          — Vertices[], SmoothingGroup, MaterialName, GroupNames[]
├── Lines[]          — VertexIndices[], TexCoordIndices[]
├── Points[]         — VertexIndices[]
├── Groups{}         — Name → FaceIndices[], LineIndices[], PointIndices[]
├── Objects{}        — Name → FaceIndices[], LineIndices[], PointIndices[]
├── Materials{}      — Name → ObjMaterial (colors, scalars, textures, PBR)
├── FreeFormBodies[] — Curves, surfaces, trims (optional)
└── Comments[]       — Preserved comments (optional)

Using MonoGame?

Use HxOBJ.MonoGame — loads OBJ files into a ModelKit Scene with PBR materials, vertex colors, tangent computation, and smoothing group support.

License

MIT

Contact

Discord: sameplayer