models

package
v1.5.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 21, 2026 License: 0BSD Imports: 19 Imported by: 0

Documentation

Overview

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

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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.

func (*GLTFLoader) LoadFromFS added in v1.5.0

func (l *GLTFLoader) LoadFromFS(fsys fs.FS, path string) (*Mesh, error)

LoadFromFS loads a GLTF or GLB file from an fs.FS 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 LoadGLBFromFS added in v1.5.0

func LoadGLBFromFS(fsys fs.FS, path string) (*Mesh, error)

LoadGLBFromFS loads a binary GLTF (.glb) file from an fs.FS.

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 LoadGLBWithTextureFromFS added in v1.5.0

func LoadGLBWithTextureFromFS(fsys fs.FS, path string) (*Mesh, image.Image, error)

LoadGLBWithTextureFromFS loads a GLB file from an fs.FS 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 LoadGLTFWithTexturesFromFS added in v1.5.0

func LoadGLTFWithTexturesFromFS(fsys fs.FS, path string) (*Mesh, map[int][]byte, error)

LoadGLTFWithTexturesFromFS loads a GLTF file from an fs.FS and extracts 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 LoadOBJFromFS added in v1.5.0

func LoadOBJFromFS(fsys fs.FS, path string) (*Mesh, error)

LoadOBJFromFS loads an OBJ file from a filesystem interface.

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 LoadSTLFromFS added in v1.5.0

func LoadSTLFromFS(fsys fs.FS, path string) (*Mesh, error)

LoadSTLFromFS loads an STL file from a filesystem interface.

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() (minV, maxV 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL