@realsee/equirect-toolbox

Node.js command-line tools for working with equirectangular panoramas. The package can render perspective (rectlinear) screenshots and convert between equirectangular images and six-face cube maps.

Features

• Render a perspective screenshot from an equirectangular panorama with Euler angles, a rotation matrix, or a quaternion.
• Convert an equirectangular panorama to six cube-face images.
• Convert six cube-face images described by a cube.json manifest back to an equirectangular panorama.
• Run from npm without a browser or a separate Three.js application.

Requirements

• Node.js 20 or 22. The supported range is declared as ^20 || ^22 in package.json.
• A platform supported by the native dependencies gl and @napi-rs/canvas.

Installation

Install the package in a project:

X Server and Xvfb

On Linux servers, containers, and CI runners without a display server, run the rendering command through Xvfb, a virtual X server:

sudo apt-get update
sudo apt-get install -y xvfb

Use xvfb-run to provide a temporary display for the CLI. The -a option selects an available display number automatically:

xvfb-run -a \
  --server-args="-screen 0 1920x1080x24" \
  equirect-toolbox rectlinear \
  --input equirect.jpg \
  --output perspective.jpg \
  --config rectlinear-matrix.json

The same wrapper can be used with npx and the cube conversion commands:

xvfb-run -a npx equirect-toolbox equirect2cube \
  --input equirect.jpg \
  --output cube.json

On macOS, xvfb-run is generally not required for local execution. If a headless environment reports that no display is available, install Xvfb through the operating system image and run the command with xvfb-run as shown above.

npm install @realsee/equirect-toolbox

The package provides the equirect-toolbox executable. It can be invoked with npx:

npx equirect-toolbox --help

Or invoke the binary from an npm script or from node_modules/.bin after installation.

CLI usage

rectlinear

Render a perspective screenshot from an equirectangular image:

equirect-toolbox rectlinear \
  --input equirect.jpg \
  --output perspective.jpg \
  --config rectlinear-matrix.json

The output format is selected from the output file extension (.jpg, .jpeg, .png, or .avif). AVIF input images are also supported by the underlying image decoder.

Generate a rectlinear config

Use one of the built-in configuration templates as a starting point:

equirect-toolbox rectlinear --init-config euler --output rectlinear-euler.json
equirect-toolbox rectlinear --init-config matrix --output rectlinear-matrix.json
equirect-toolbox rectlinear --init-config quaternion --output rectlinear-quaternion.json

The generated file can be edited and passed with --config.

Rectlinear config format

All rectlinear configs contain a viewport and a camera field:

{
  "viewport": {
    "width": 1920,
    "height": 1080
  },
  "camera": {
    "vfov": 60,
    "yaw": 0,
    "pitch": 0,
    "roll": 0
  }
}

• viewport.width and viewport.height are the output dimensions in pixels.
• camera.vfov is the vertical field of view in degrees.
• The camera orientation can be specified in one of three forms:
  • Euler angles: yaw, pitch, and roll, in degrees.
  • A row-major 3x3 rotation matrix.
  • A quaternion with x, y, z, and w components.

The package includes the schema and templates in configs/schema and configs/templates. The generated templates are also available in the source repository.

equirect2cube

Convert an equirectangular panorama into six cube-face images and a manifest:

equirect-toolbox equirect2cube \
  --input equirect.jpg \
  --output cube.json

When cube.json does not exist, the command creates it and uses JPEG paths by default. The face size is calculated automatically from the input image and rounded up to a power of two.

When cube.json already exists, its six paths and file extensions determine where and how the face images are written. This means the command does not need separate --format or --face-size options.

To create an empty manifest without converting an image:

equirect-toolbox equirect2cube \
  --init-cube-json \
  --output cube.json

cube2equirect

Convert the six cube faces referenced by a manifest into an equirectangular panorama:

equirect-toolbox cube2equirect \
  --input cube.json \
  --output equirect.jpg

The input must be a cube.json manifest. The six images must have the same square, power-of-two dimensions. The output dimensions are four times the face size by two times the face size.

You can also initialize a manifest with this command:

equirect-toolbox cube2equirect \
  --init-cube-json \
  --output cube.json

Programmatic API

The package also exposes the conversion functions from subpath imports. JSON objects can be passed directly for rectlinear configs and cube manifests:

import { renderRectlinear } from "@realsee/equirect-toolbox/rectlinear";
import { convertEquirectToCube } from "@realsee/equirect-toolbox/equirect2cube";
import { convertCubeToEquirect } from "@realsee/equirect-toolbox/cube2equirect";

await renderRectlinear({
  input: "equirect.jpg",
  output: "perspective.jpg",
  config: {
    viewport: { width: 1920, height: 1080 },
    camera: { vfov: 60, yaw: 0, pitch: 0, roll: 0 },
  },
});

await convertEquirectToCube({
  input: "equirect.jpg",
  output: {
    px: "cube_px.jpg",
    nx: "cube_nx.jpg",
    py: "cube_py.jpg",
    ny: "cube_ny.jpg",
    pz: "cube_pz.jpg",
    nz: "cube_nz.jpg",
  },
});

await convertCubeToEquirect({
  input: {
    px: "cube_px.jpg",
    nx: "cube_nx.jpg",
    py: "cube_py.jpg",
    ny: "cube_ny.jpg",
    pz: "cube_pz.jpg",
    nz: "cube_nz.jpg",
  },
  output: "equirect.jpg",
});

For object inputs and outputs, relative image paths are resolved from process.cwd(). Passing an object as equirect2cube.output configures the six face image paths and does not write a cube.json manifest. String paths retain the file-based behavior described above.

cube.json manifest

A manifest contains one path for each cube face:

{
  "px": "cube_px.jpg",
  "nx": "cube_nx.jpg",
  "py": "cube_py.jpg",
  "ny": "cube_ny.jpg",
  "pz": "cube_pz.jpg",
  "nz": "cube_nz.jpg"
}

The paths are resolved relative to the directory containing cube.json, not relative to the current working directory.

| Key | Cube face | | ---- | ---------- | | px | positive X | | nx | negative X | | py | positive Y | | ny | negative Y | | pz | positive Z | | nz | negative Z |

The file extension in each path selects the output image format. Use .jpg/.jpeg for JPEG, .png for PNG, or .avif for AVIF. The manifest schema is included at configs/schema/cube.schema.json.

Package contents

The published package contains:

• dist: compiled JavaScript, declarations, declaration maps, and source maps.
• configs/schema: JSON Schemas used to validate rectlinear configs and cube manifests.
• configs/templates: ready-to-copy configuration and manifest templates.
• README.md and package metadata.