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

Acknowledgments

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

Resources

Author

Alex Marinov - Konsept Design Limited

This site is open source. Improve this page.