models

Documentation

Overview

Package models provides 3D model loading and representation for Trophy.

Index

• type Face
• type GLTFLoader
  • func NewGLTFLoader() *GLTFLoader
  • func (l *GLTFLoader) Load(path string) (*Mesh, error)
• type Material
• type Mesh
  • func LoadGLB(path string) (*Mesh, error)
  • func LoadGLBWithTexture(path string) (*Mesh, image.Image, error)
  • func LoadGLTFWithTextures(path string) (*Mesh, map[int][]byte, error)
  • func LoadOBJ(path string) (*Mesh, error)
  • func LoadOBJSmooth(path string) (*Mesh, error)
  • func LoadSTL(path string) (*Mesh, error)
  • func LoadSTLClean(path string) (*Mesh, error)
  • func LoadSTLSmooth(path string) (*Mesh, error)
  • func NewMesh(name string) *Mesh
  • func (m *Mesh) CalculateBounds()
  • func (m *Mesh) CalculateNormals()
  • func (m *Mesh) CalculateSmoothNormals()
  • func (m *Mesh) Center() math3d.Vec3
  • func (m *Mesh) CleanMesh() int
  • func (m *Mesh) Clone() *Mesh
  • func (m *Mesh) DeduplicateFaces() int
  • func (m *Mesh) GetBounds() (min, max math3d.Vec3)
  • func (m *Mesh) GetFace(i int) [3]int
  • func (m *Mesh) GetFaceMaterial(i int) int
  • func (m *Mesh) GetMaterial(i int) *Material
  • func (m *Mesh) GetVertex(i int) (pos, normal math3d.Vec3, uv math3d.Vec2)
  • func (m *Mesh) MaterialCount() int
  • func (m *Mesh) RemoveDegenerateFaces() int
  • func (m *Mesh) RemoveInternalFaces() int
  • func (m *Mesh) RemoveUnreferencedVertices()
  • func (m *Mesh) Size() math3d.Vec3
  • func (m *Mesh) Transform(mat math3d.Mat4)
  • func (m *Mesh) TriangleCount() int
  • func (m *Mesh) VertexCount() int
• type MeshVertex
• type OBJLoader
  • func NewOBJLoader() *OBJLoader
  • func (l *OBJLoader) Load(r io.Reader, name string) (*Mesh, error)
  • func (l *OBJLoader) LoadFile(path string) (*Mesh, error)
• type STLLoader
  • func NewSTLLoader() *STLLoader
  • func (l *STLLoader) Load(r io.Reader, name string) (*Mesh, error)
  • func (l *STLLoader) LoadBytes(data []byte, name string) (*Mesh, error)
  • func (l *STLLoader) LoadFile(path string) (*Mesh, error)

Types

type Face

type Face struct {
	V        [3]int // Indices into Mesh.Vertices
	Material int    // Index into Mesh.Materials (-1 for no material)
}

Face represents a triangle face with vertex indices and material reference.

type GLTFLoader

type GLTFLoader struct {
	// Options
	CalculateNormals bool
	SmoothNormals    bool
}

GLTFLoader loads GLTF/GLB files into Mesh format.

func NewGLTFLoader

func NewGLTFLoader() *GLTFLoader

NewGLTFLoader creates a new GLTF loader with default options.

func (*GLTFLoader) Load

func (l *GLTFLoader) Load(path string) (*Mesh, error)

Load loads a GLTF or GLB file and returns a Mesh.

type Material

type Material struct {
	Name       string
	BaseColor  [4]float64  // RGBA in 0-1 range
	Metallic   float64     // 0 = dielectric, 1 = metal
	Roughness  float64     // 0 = smooth, 1 = rough
	BaseMap    image.Image // Optional base color texture
	HasTexture bool
}

Material represents a PBR material from GLTF.

type Mesh

type Mesh struct {
	Name      string
	Vertices  []MeshVertex
	Faces     []Face
	Materials []Material

	// Bounding box (calculated on load)
	BoundsMin math3d.Vec3
	BoundsMax math3d.Vec3
}

Mesh represents a 3D mesh with vertices, faces, and materials.

func LoadGLB

func LoadGLB(path string) (*Mesh, error)

LoadGLB loads a binary GLTF (.glb) file.

func LoadGLBWithTexture

func LoadGLBWithTexture(path string) (*Mesh, image.Image, error)

LoadGLBWithTexture loads a GLB file and returns the mesh plus the first embedded texture. Returns (mesh, texture image, error). Texture may be nil if none embedded.

func LoadGLTFWithTextures

func LoadGLTFWithTextures(path string) (*Mesh, map[int][]byte, error)

LoadGLTFWithTextures loads a GLTF file and extracts embedded textures. Returns the mesh and a map of image index to texture data.

func LoadOBJ

func LoadOBJ(path string) (*Mesh, error)

LoadOBJ is a convenience function to load an OBJ file with default settings.

func LoadOBJSmooth

func LoadOBJSmooth(path string) (*Mesh, error)

LoadOBJSmooth loads an OBJ file with smooth normals.

func LoadSTL

func LoadSTL(path string) (*Mesh, error)

LoadSTL is a convenience function to load an STL file with default settings.

func LoadSTLClean

func LoadSTLClean(path string) (*Mesh, error)

LoadSTLClean loads an STL file and cleans the mesh. This removes degenerate faces, duplicate faces, and internal geometry.

func LoadSTLSmooth

func LoadSTLSmooth(path string) (*Mesh, error)

LoadSTLSmooth loads an STL file with smooth normals.

func NewMesh

func NewMesh(name string) *Mesh

NewMesh creates an empty mesh.

func (*Mesh) CalculateBounds

func (m *Mesh) CalculateBounds()

CalculateBounds computes the axis-aligned bounding box.

func (*Mesh) CalculateNormals

func (m *Mesh) CalculateNormals()

CalculateNormals computes face normals and assigns them to vertices. This is a simple flat-shading approach; for smooth shading, normals should be averaged per-vertex.

func (*Mesh) CalculateSmoothNormals

func (m *Mesh) CalculateSmoothNormals()

CalculateSmoothNormals computes averaged normals for smooth shading.

func (*Mesh) Center

func (m *Mesh) Center() math3d.Vec3

Center returns the center of the bounding box.

func (*Mesh) CleanMesh

func (m *Mesh) CleanMesh() int

CleanMesh performs all mesh cleanup operations: 1. Remove degenerate faces (zero area) 2. Remove internal faces (coplanar opposing pairs) - must come before dedup! 3. Remove duplicate faces 4. Remove unreferenced vertices Returns the total number of faces removed.

func (*Mesh) Clone

func (m *Mesh) Clone() *Mesh

Clone creates a deep copy of the mesh.

func (*Mesh) DeduplicateFaces

func (m *Mesh) DeduplicateFaces() int

DeduplicateFaces removes duplicate faces from the mesh. Two faces are considered duplicates if they have the same three vertices (regardless of winding order). When duplicates are found, only the first occurrence is kept. Returns the number of faces removed.

func (*Mesh) GetBounds

func (m *Mesh) GetBounds() (min, max math3d.Vec3)

GetBounds returns the axis-aligned bounding box. Implements render.BoundedMeshRenderer interface.

func (*Mesh) GetFace

func (m *Mesh) GetFace(i int) [3]int

GetFace returns the vertex indices for face i. Implements render.MeshRenderer interface.

func (*Mesh) GetFaceMaterial

func (m *Mesh) GetFaceMaterial(i int) int

GetFaceMaterial returns the material index for face i. Returns -1 if no material assigned.

func (*Mesh) GetMaterial

func (m *Mesh) GetMaterial(i int) *Material

GetMaterial returns the material at index i. Returns nil if index is out of bounds or -1.

func (*Mesh) GetVertex

func (m *Mesh) GetVertex(i int) (pos, normal math3d.Vec3, uv math3d.Vec2)

GetVertex returns the position, normal, and UV for vertex i. Implements render.MeshRenderer interface.

func (*Mesh) MaterialCount

func (m *Mesh) MaterialCount() int

MaterialCount returns the number of materials.

func (*Mesh) RemoveDegenerateFaces

func (m *Mesh) RemoveDegenerateFaces() int

RemoveDegenerateFaces removes faces with zero or near-zero area. Returns the number of faces removed.

func (*Mesh) RemoveInternalFaces

func (m *Mesh) RemoveInternalFaces() int

RemoveInternalFaces removes pairs of coplanar faces that face opposite directions. These typically occur at the boundaries of merged/combined meshes where internal geometry should be removed. For each pair of faces sharing the same vertices but with opposite normals, both faces are removed. Returns the number of faces removed.

func (*Mesh) RemoveUnreferencedVertices

func (m *Mesh) RemoveUnreferencedVertices()

RemoveUnreferencedVertices removes vertices that are not referenced by any face. This compacts the vertex array and updates face indices accordingly.

func (*Mesh) Size

func (m *Mesh) Size() math3d.Vec3

Size returns the dimensions of the bounding box.

func (*Mesh) Transform

func (m *Mesh) Transform(mat math3d.Mat4)

Transform applies a transformation matrix to all vertices.

func (*Mesh) TriangleCount

func (m *Mesh) TriangleCount() int

TriangleCount returns the number of triangles.

func (*Mesh) VertexCount

func (m *Mesh) VertexCount() int

VertexCount returns the number of vertices.

type MeshVertex

type MeshVertex struct {
	Position math3d.Vec3
	Normal   math3d.Vec3
	UV       math3d.Vec2
}

MeshVertex holds all vertex attributes.

type OBJLoader

type OBJLoader struct {
	// Options
	CalculateNormals bool // If true, calculate normals if not provided
	SmoothNormals    bool // If true, use smooth shading (averaged normals)
}

OBJLoader loads Wavefront OBJ files.

func NewOBJLoader

func NewOBJLoader() *OBJLoader

NewOBJLoader creates a new OBJ loader with default settings.

func (*OBJLoader) Load

func (l *OBJLoader) Load(r io.Reader, name string) (*Mesh, error)

Load parses an OBJ from a reader.

func (*OBJLoader) LoadFile

func (l *OBJLoader) LoadFile(path string) (*Mesh, error)

LoadFile loads an OBJ file from disk.

type STLLoader

type STLLoader struct {
	// Options
	SmoothNormals  bool    // If true, average normals per-vertex for smooth shading
	NoDedupe       bool    // If true, don't deduplicate vertices (each triangle gets its own)
	CleanMesh      bool    // If true, clean mesh after loading (remove degenerate/duplicate/internal faces)
	MergeTolerance float64 // Tolerance for vertex merging (default 1e-6, 0 = exact match)
}

STLLoader loads STL (stereolithography) files in both ASCII and binary formats.

func NewSTLLoader

func NewSTLLoader() *STLLoader

NewSTLLoader creates a new STL loader with default settings.

func (*STLLoader) Load

func (l *STLLoader) Load(r io.Reader, name string) (*Mesh, error)

Load parses STL from a reader. Note: This reads the entire content into memory to detect format.

func (*STLLoader) LoadBytes

func (l *STLLoader) LoadBytes(data []byte, name string) (*Mesh, error)

LoadBytes parses STL from a byte slice.

func (*STLLoader) LoadFile

func (l *STLLoader) LoadFile(path string) (*Mesh, error)

LoadFile loads an STL file from disk.