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