npm package: @roswellcity/glb-metadata-toolkit
Description: Extract rich metadata from GLB/GLTF as a library, CLI, or pipeline step.
Latest version: 0.1.0

# @roswellcity/glb-metadata-toolkit

[![API Docs](https://img.shields.io/badge/API-Documentation-blue)](./docs/README.md)
[![TypeDoc](https://img.shields.io/badge/TypeDoc-Generated-green)](./docs/README.md)

Extract rich metadata from GLB/GLTF files as a library, CLI tool, or pipeline step. Get scene hierarchies, bounding boxes, mesh statistics, and more in JSON, CSV, XML, or plain text formats.

## Features

- **Flexible usage**: Works as a library, CLI, or pipeline step
- **Multiple output formats**: JSON, CSV, XML, TXT
- **Detailed model insights**: Scene graphs, node hierarchies, bounding boxes, mesh stats
- **Pipeline-friendly**: Supports stdin/stdout streaming
- **Typed and modern**: TypeScript definitions, Node 18+, ESM + CommonJS

## Installation

```bash
# Library usage
pnpm add @roswellcity/glb-metadata-toolkit

# CLI usage (global)
pnpm add -g @roswellcity/glb-metadata-toolkit

# CLI usage (npx)
pnpx @roswellcity/glb-metadata-toolkit extract model.glb
```
## Documentation

- [🚀 Quick Start](#quick-start)
- [📖 API Reference](./docs/README.md)
- [🎯 Main Class: GltfMetadataExtractor](./docs/classes/GltfMetadataExtractor.md)
- [📋 Interfaces](./docs/interfaces/FileMetadata.md)
- [⚙️ Extract Options](./docs/interfaces/ExtractOptions.md)

## Quick Start

### Library Usage

```javascript
import { GltfMetadataExtractor } from '@roswellcity/glb-metadata-toolkit'

const extractor = new GltfMetadataExtractor()
const metadata = await extractor.extract('model.glb')

// Access scene data
console.log(metadata.scenes[0].center)
console.log(metadata.scenes[0].boundingBox)
console.log(metadata.scenes[0].nodes.length)
```

### CLI Usage

```bash
# JSON to stdout
glb-metadata extract model.glb

# CSV to file
glb-metadata extract model.glb --format csv --out model.csv

# XML via pipe
cat model.glb | glb-metadata extract - --format xml > model.xml

# Pipeline usage
cat model.glb | glb-metadata extract - --format json --no-pretty | jq '.scenes[0].boundingBox'
```

## CLI Reference

```bash
glb-metadata extract [input] [options]
```

**Arguments:**
- `input`: Path to GLB/GLTF file, or `-` for stdin

**Options:**
- `-f, --format <fmt>`: Output format: `json|csv|xml|txt` (default: `json`)
- `-o, --out <path>`: Write to file instead of stdout
- `--no-pretty`: Disable pretty JSON formatting

## Output Formats

### JSON (Default)
Complete hierarchical metadata with all fields preserved.

### CSV
Flattened view with one row per node, suitable for spreadsheet analysis:
```
sceneIndex,sceneName,nodeIndex,nodeName,path,centerX,centerY,centerZ,minX,minY,minZ,maxX,maxY,maxZ,vertexCount,primitiveCount
```

### XML
Structured XML representation of the complete metadata tree.

### TXT
Human-readable summary with indented hierarchy:
```
File: model.glb (2048 bytes)
Scene #0 MainScene
 Nodes: 5
 BBox: min -1.0, -1.0, -1.0 max 1.0, 1.0, 1.0
 Center: 0.0, 0.0, 0.0
 - Node #0 RootNode (Node)
 - Node #1 MeshNode (Mesh)
 Mesh: 1 prims, 1024 vertices
```

## Examples

### Extract All Scene Centers

```javascript
import { GltfMetadataExtractor } from '@roswellcity/glb-metadata-toolkit'

const extractor = new GltfMetadataExtractor()
const meta = await extractor.extract('model.glb')

meta.scenes.forEach(scene => {
  console.log(`Scene "${scene.name}": ${scene.center.join(', ')}`)
})
```

### Find Large Meshes

```javascript
const meta = await extractor.extract('model.glb')

const largeMeshes = meta.scenes
  .flatMap(s => s.nodes)
  .filter(n => n.mesh && n.mesh.vertexCount > 10000)

largeMeshes.forEach(node => {
  console.log(`${node.name}: ${node.mesh.vertexCount} vertices`)
})
```

### Pipeline Processing

```bash
# Extract centers of all scenes
find ./models -name "*.glb" | while read file; do
  echo -n "$file: "
  glb-metadata extract "$file" --no-pretty | jq -r '.scenes[0].center | @csv'
done

# Generate CSV report
glb-metadata extract model.glb --format csv | \
  awk -F',' 'NR>1 && $15>1000 {print $4 ": " $15 " vertices"}'
```

## Development

### Setup

```bash
git clone <repo>
cd glb-metadata-toolkit
pnpm install
```

### Scripts

```bash
pnpm build          # Build library and CLI
pnpm test           # Run tests
pnpm lint           # Lint code
pnpm format         # Format code
pnpm typecheck      # Type checking
pnpm docs           # Generate documentation
```

### Building

The project uses [tsup](https://tsup.egoist.dev/) to build both ESM and CommonJS outputs:

- `dist/index.mjs` - ESM library
- `dist/index.cjs` - CommonJS library  
- `dist/cli.cjs` - CLI executable
- `bin/glb-metadata.cjs` - CLI entry point

## Requirements

- Node.js 18 or higher
- Compatible with GLB and GLTF 2.0 files

## License

MIT

## Contributing

Issues and pull requests welcome. Please run `pnpm lint` and `pnpm test` before submitting.