npm package: @mrpjevans/threedom
Description: A simple 3D image processing library and command line tool
Author: PJ Evans
Latest version: 1.3.0

# Threedom

A Node.js library and CLI tool for manipulating and converting 3D stereo images and spatial videos.

## Overview

Threedom is a versatile tool for processing stereoscopic 3D images and spatial videos. It supports various 3D image formats including MPO, HEIC spatial photos, and can convert between different viewing formats like side-by-side, anaglyph, and more. It also supports converting Apple spatial videos to side-by-side format.

## Features

- Load stereoscopic images from MPO and HEIC spatial photos
- Convert between different 3D formats
- Create anaglyphs (red-cyan 3D)
- Generate side-by-side images with multiple viewing options
- Convert spatial videos to side-by-side format (MOV to MOV/MP4)
- Process multiple images or videos
- Customize output with various options

## Installation

```bash
npm install @mrpjevans/threedom
```

## Requirements

- Node.js 14+
- ImageMagick (for anaglyph conversion)
- On macOS with Apple Silicon:
  - The `spatial` command is used for HEIC processing and video conversion
  - `ffmpeg` is required for MP4 output

```bash
brew install spatial
brew install imagemagick
brew install ffmpeg
```

## Module Usage

```typescript
import { Threedom } from "threedom";

async function example() {
	// Create a new Threedom instance
	const threedom = new Threedom();

	// Load an MPO file
	await threedom.load("path/to/image.mpo");

	// Or load a HEIC spatial photo
	// await threedom.load('path/to/image.heic');

	// Or load left and right images separately
	// await threedom.load(['path/to/left.jpg', 'path/to/right.jpg']);

	// Generate a side-by-side image
	const sideByImage = await threedom.toSideBySide({
		style: "parallel", // 'parallel', 'cross', or 'triplet'
		half: false, // resize to half width
		sixteenNine: false, // pad to 16:9 aspect ratio
	});

	// Save the result
	const fs = require("fs");
	fs.writeFileSync("output.jpg", sideByImage);

	// Or create an anaglyph
	const anaglyphImage = await threedom.toAnaglyph(false);
	fs.writeFileSync("anaglyph.jpg", anaglyphImage);

	// Get the original left and right images
	const [leftImage, rightImage] = threedom.toPair();

	// On macOS with Apple Silicon, convert to HEIC spatial photo
	const heicData = await threedom.toHeic();
	fs.writeFileSync("output.heic", heicData);

	// Convert a spatial video to side-by-side format
	await threedom.convertSpatialVideo(
		"input.mov", // Input spatial video
		"output.mp4", // Output file (MOV or MP4)
		false // Optional: half width
	);
}

example().catch(console.error);
```

## CLI Usage

Threedom also includes a command-line interface for quick processing.

### Basic Usage

```bash
# Process an image
npx @mrpjevans/threedom input.mpo --format side-by-side --output output.jpg

# Convert a spatial video (automatically detected by .mov extension)
npx @mrpjevans/threedom input.mov --output output.mp4
```

### Command-line Options

```
Usage: threedom [options] <input>

Options:
  --output, -o       Output file or directory                      [string]
  --format, -f       Output format (ignored for spatial videos)
                     [choices: "anaglyph", "side-by-side", "heic", "pair"]
                                                       [default: "side-by-side"]
  --style, -s        Side-by-side style (ignored for spatial videos)
                     [choices: "parallel", "cross", "triplet"]
                                                          [default: "parallel"]
  --half, -h         Resize images/videos to half width   [boolean] [default: false]
  --sixteen-nine     Pad images to 16:9 ratio (ignored for spatial videos)
                                                         [boolean] [default: false]
  --bw               Black and white anaglyph (ignored for spatial videos)
                                                         [boolean] [default: false]
  --help             Show help                                     [boolean]
```

### Examples

Convert an MPO file to side-by-side format:

```bash
npx @mrpjevans/threedom image.mpo --format side-by-side --style parallel
```

Create an anaglyph (red-cyan 3D image):

```bash
npx @mrpjevans/threedom image.mpo --format anaglyph --output anaglyph.jpg
```

Process multiple files using a glob pattern:

```bash
npx @mrpjevans/threedom "photos/*.mpo" --format side-by-side --output processed/
```

Create a black and white anaglyph:

```bash
npx @mrpjevans/threedom image.mpo --format anaglyph --bw --output bw-anaglyph.jpg
```

Extract left and right images from an MPO file:

```bash
npx @mrpjevans/threedom image.mpo --format pair --output image_base
# Creates image_base_left.jpg and image_base_right.jpg
```

Create a side-by-side image optimized for cross-view with 16:9 aspect ratio:

```bash
npx @mrpjevans/threedom image.mpo --format side-by-side --style cross --sixteen-nine
```

Convert a spatial video to side-by-side MP4:

```bash
npx @mrpjevans/threedom video.mov --output converted.mp4
```

Convert a spatial video to half-width MOV:

```bash
npx @mrpjevans/threedom video.mov --half --output converted.mov
```

Process multiple spatial videos:

```bash
npx @mrpjevans/threedom "videos/*.mov" --output processed/
```

## Supported Formats

### Input Formats

- MPO (Multi Picture Object) - Common format for 3D cameras
- HEIC (High Efficiency Image Format) - Spatial photos from Apple devices
- Image pairs (two separate image files)
- MOV (Apple spatial videos)

### Output Formats

- Anaglyph - Red-cyan 3D images viewable with colored glasses
- Side-by-side - Various viewing styles (parallel, cross-view, triplet)
- HEIC - Apple spatial photos (macOS with Apple Silicon only)
- Pair - Separate left and right images
- Side-by-side video (MOV or MP4) - Converted from spatial videos

## Platform-Specific Features

- HEIC processing and spatial video conversion requires macOS with Apple Silicon
- MP4 video output requires ffmpeg
- Anaglyph creation requires ImageMagick

## License

MIT