three-iges-loader

IGESLoader is a modern TypeScript-native IGES file loader for Three.js.

Warning

This package is currently in active development and may not be stable. Use with caution.

Note

Wireframe entities (points, lines, arcs, paths, NURBS curves) are supported first. Surfaces and B-rep solids are planned — see docs/ROADMAP.md.

Features

✨ Layered architecture — iges-core parser (no Three.js) + thin IGESLoader
📦 Modern ESM/CJS — Dual package format with tree-shaking support
🔧 Typed geometry model — parseAndResolveIGES() for custom pipelines
⚡ Fast — Optimized build with tsup and pnpm workspaces
🧪 Tested — Unit tests + Wikipedia slot fixture
🤖 AI-friendly — See AGENTS.md and docs/ENTITY_IMPLEMENTATION.md

Architecture

iges-core/          Parse IGES → ResolvedIGESModel (geometry[])
src/three/          toThreeGroup() → THREE.Group
IGESLoader.ts       FileLoader + parse + tessellate

Full details: docs/ARCHITECTURE.md · Roadmap: docs/ROADMAP.md

Install

three is a peer dependency — install it alongside this package (any version >=0.160.0 is supported; development targets Three.js r184).

pnpm add three-iges-loader three

Or using npm:

npm install three-iges-loader three

Or using yarn:

yarn add three-iges-loader three

Usage

JavaScript

import * as THREE from "three";
import { IGESLoader } from "three-iges-loader";

const loader = new IGESLoader();

const iges_file_path = "/file.iges";

loader.load(
  // resource URL
  iges_file_path,
  // called when load is complete
  function (object) {
    sceneGeometry.add(object);
  },
  // called when loading is in progress
  function (xhr) {
    console.log((xhr.loaded / xhr.total) * 100 + "% loaded");
  },
  // called when loading has errors
  function (error) {
    console.log("Error: " + error);
  }
);

TypeScript

import * as THREE from "three";
import { IGESLoader } from "three-iges-loader";

const scene = new THREE.Scene();
const loader = new IGESLoader();

loader.load(
  "/path/to/file.iges",
  (geometry: THREE.Group) => {
    scene.add(geometry);
  },
  (xhr: ProgressEvent) => {
    console.log(`${(xhr.loaded / xhr.total) * 100}% loaded`);
  },
  (error: Error | ErrorEvent) => {
    console.error("Error loading IGES file:", error);
  }
);

React Three Fiber

import { useLoader } from "@react-three/fiber";
import { IGESLoader } from "three-iges-loader";

function IgesModel({ url }: { url: string }) {
  const group = useLoader(IGESLoader, url);
  return <primitive object={group} />;
}

Advanced — parse without the loader

import { parseAndResolveIGES, toThreeGroup } from "three-iges-loader";

const text = await fetch("/model.igs").then((r) => r.text());
const model = parseAndResolveIGES(text);
const group = toThreeGroup(model, { convertZUpToYUp: true });
scene.add(group);

Development

Prerequisites

• Node.js >= 24.0.0 (LTS)
• pnpm (recommended) or npm

Setup

# Install dependencies (pnpm workspace: root + packages/iges-core)
pnpm install

# Build iges-core + three-iges-loader
pnpm build

# Run all tests (core unit + loader integration)
pnpm test

# Run tests in watch mode
pnpm test:watch

# Type check
pnpm type-check

# Lint and format
pnpm lint
pnpm format

Running the Example

The package includes a modern Vite-based example:

# Start the development server
pnpm dev:example

# Build the example
pnpm build:example

Then open http://localhost:3000 in your browser.

API Reference

IGESLoader

Constructor

new IGESLoader(manager?: THREE.LoadingManager)

Methods

load(url, onLoad, onProgress?, onError?)

Load an IGES file from a URL.

• url: string - The URL or path to the IGES file
• onLoad: (geometry: THREE.Group) => void - Callback when loading is complete
• onProgress?: (event: ProgressEvent) => void - Callback for loading progress
• onError?: (event: ErrorEvent | Error) => void - Callback when an error occurs

parse(data)

Parse IGES file content.

• data: string - The IGES file content as string
• Returns: THREE.Group - A Three.js Group containing the parsed geometry

Type exports

import type { ResolvedIGESModel, GeometryEntity, LineGeometry } from "three-iges-loader";

Supported IGES entities (Phase B)

Type	Name	Status
116	Point	✅
110	Line	✅
100	Circular arc	✅
106	Copious data / paths	✅ partial forms
126	Rational B-spline curve	✅ sampled
124	Transform matrix	✅ resolve only
102	Composite curve	⬜ roadmap
128+	Surfaces / B-rep	⬜ deferred

Contributing

Contributions are welcome — see CONTRIBUTING.md.

Doc	Purpose
CONTRIBUTING.md	Setup, PR flow, changesets
AGENTS.md	AI coding assistants
RELEASING.md	Versioning & npm (maintainers)
docs/GITHUB_SETUP.md	One-time GitHub/npm configuration
SECURITY.md	Vulnerability reporting

Releases: Semantic versioning via Changesets; merges to main open a Version Packages PR, then publish to npm automatically.

License

MIT © Alex Marinov

Acknowledgments

• Based on the original work by Alex Marinov
• Maintained by Konsept Design
• Built with Three.js

Resources

• IGES File Specification
• IGES Version 5.3 Specification
• IGES Version 6.0 Specification
• IGES on Wikipedia

Author

Alex Marinov - Konsept Design Limited