krpanos-tools

A set of CLI tools for processing equirectangular panoramic images: geotagging, cube face generation, and Excel metadata export.

Installation

npm install -g krpanos-tools

CLI Commands

panos-geotag

Assigns GPS coordinates and heading to panoramic images using data from a GeoJSON file.

Usage:

panos-geotag [options]

Options:

| Option | Description | Default | |---|---|---| | -i, --imagesFolder <path> | Path to the images folder | . | | -j, --jsonFile <string> | GeoJSON filename | imagesdir.json |

GeoJSON format:

The JSON file must follow GeoJSON FeatureCollection structure with each feature containing:

• properties.pano — image filename
• properties.latitude — GPS latitude
• properties.longitude — GPS longitude
• heading (optional) — GPS image direction (random if omitted)

Example:

panos-geotag -i ./my-panos -j geodata.json

panos-faces

Converts equirectangular panoramic images into cubemap faces (6 faces per image), generates a preview strip and a thumbnail, and exports image metadata to an Excel file.

Usage:

panos-faces [options]

Options:

| Option | Description | Default | |---|---|---| | -i, --imagesFolder <path> | Path to the images folder | . | | -o, --outputFolder <path> | Path to the output folder (relative to images folder) | cubes | | -u, --urlPanos <type> | Base URL for panoramas in the exported Excel | /panos/ |

Output structure:

<outputFolder>/
  <image_name>/
    pano_f.jpg    # front face
    pano_b.jpg    # back face
    pano_u.jpg    # up face
    pano_d.jpg    # down face
    pano_l.jpg    # left face
    pano_r.jpg    # right face
    preview.jpg   # 256×1536 vertical strip of all faces
    thumb.jpg     # 240×240 thumbnail (front face)
excel/
  <timestamp>.xlsx

Example:

panos-faces -i ./static -o cubes -u /panos/

panos-excel

Reads EXIF metadata (GPS coordinates, date, heading) from panoramic images and exports it to an Excel file. Headings are computed as rhumb line bearings between consecutive images.

Usage:

panos-excel [options]

Options:

| Option | Description | Default | |---|---|---| | -i, --imagesFolder <path> | Path to the images folder | . | | -u, --urlPanos <type> | Base URL for panoramas in the exported Excel | /panos/ |

Output:

An .xlsx file is created in excel/<timestamp>.xlsx with columns:

| Column | Description | |---|---| | url_pano | Base URL prefix | | pano | Image name (without extension) | | date | Original capture date (ISO 8601) | | latitude | GPS latitude | | longitude | GPS longitude | | heading | Rhumb line bearing to the next image |

Example:

panos-excel -i ./static -u /panos/

Supported Image Formats

.jpg, .jpeg, .png, .tiff

Dependencies

• exiftool-vendored — EXIF read/write
• canvas — Image manipulation (cube faces, previews, thumbnails)
• geolib — Geodesic bearing calculations
• commander — CLI argument parsing
• xlsx — Excel export

License

MIT

👨‍💻 Developer Card

Younes M'rabti

📧 Email: [email protected]
🌐 Website: youmti.net
💼 LinkedIn: younesmrabti1996