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

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

brew install spatial
brew install imagemagick
brew install ffmpeg

Module Usage

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

# 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:

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

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

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

Process multiple files using a glob pattern:

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

Create a black and white anaglyph:

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

Extract left and right images from an MPO file:

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:

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

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

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

Convert a spatial video to half-width MOV:

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

Process multiple spatial videos:

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