krpanos-tools 1.0.0 → 1.0.2

package/INSTALL

@@ -0,0 +1,57 @@
+# Installation
+
+## Global install (recommended)
+
+Install the package globally to use the CLI commands anywhere:
+
+    npm install -g krpanos-tools
+
+This makes the following commands available:
+
+    panos-geotag    Assign GPS coordinates to panoramic images
+    panos-excel     Export image EXIF metadata to Excel
+    panos-faces     Convert equirectangular images to cubemap faces
+
+## Local install
+
+    npm install krpanos-tools
+
+Then run commands via npx:
+
+    npx panos-faces -i ./my-panos -o cubes
+
+## Prerequisites
+
+- Node.js >= 16
+- ExifTool (bundled via exiftool-vendored, no manual install needed)
+- The `canvas` native module requires build tools on some platforms:
+
+  **Windows:**
+      No extra steps needed (prebuilt binaries are downloaded).
+
+  **macOS:**
+      brew install pkg-config cairo pango libpng jpeg giflib librsvg pixman
+
+  **Linux (Debian/Ubuntu):**
+      sudo apt-get install -y build-essential libcairo2-dev \
+          libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev
+
+## Build from source
+
+Clone the repository and install dependencies:
+
+    git clone https://github.com/youmtinet/krpanos-tools.git
+    cd krpanos-tools
+    yarn install
+
+Build the CLI bundles:
+
+    yarn build
+
+The bundled scripts are output to `dist/`.
+
+## Verify installation
+
+    panos-faces --help
+    panos-geotag --help
+    panos-excel --help

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Younes Mrabti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# krpanos-tools
+<div align="center">
+    <img src="assets/banner.jpg" alt="krpanos-tools logo"/>
+</div>
+
+A set of CLI tools for processing equirectangular panoramic images: geotagging, cube face generation, and Excel metadata export.
+
+## Installation
+
+```bash
+npm install -g krpanos-tools
+```
+
+## CLI Commands
+
+### `panos-geotag`
+
+Assigns GPS coordinates and heading to panoramic images using data from a GeoJSON file.
+
+**Usage:**
+
+```bash
+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:**
+
+```bash
+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:**
+
+```bash
+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:**
+
+```bash
+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:**
+
+```bash
+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:**
+
+```bash
+panos-excel -i ./static -u /panos/
+```
+
+## Supported Image Formats
+
+`.jpg`, `.jpeg`, `.png`, `.tiff`
+
+## Dependencies
+
+- [exiftool-vendored](https://www.npmjs.com/package/exiftool-vendored) — EXIF read/write
+- [canvas](https://www.npmjs.com/package/canvas) — Image manipulation (cube faces, previews, thumbnails)
+- [geolib](https://www.npmjs.com/package/geolib) — Geodesic bearing calculations
+- [commander](https://www.npmjs.com/package/commander) — CLI argument parsing
+- [xlsx](https://www.npmjs.com/package/xlsx) — Excel export
+
+## License
+
+MIT
+
+---
+
+## 👨‍💻 Developer Card
+
+<div align="center">
+    <img src="https://avatars.githubusercontent.com/u/47449165?v=4" alt="Younes M'rabti avatar" width="120" height="120" style="border-radius: 50%;" />
+
+### Younes M'rabti
+
+📧 Email: [admin@youmti.net](mailto:admin@youmti.net)  
+🌐 Website: [youmti.net](https://www.youmti.net/)  
+💼 LinkedIn: [younesmrabti1996](https://www.linkedin.com/in/younesmrabti1996/)
+</div>

package/package.json

@@ -1,27 +1,55 @@
 {
     "name": "krpanos-tools",
-    "version": "1.0.0",
-    "description": "",
+    "version": "1.0.2",
+    "description": "CLI tools for processing equirectangular panoramic images: geotagging, cubemap face generation, and Excel metadata export",
     "main": "src/equi.js",
     "scripts": {
         "panos": "node src/equi -i static -o panos",
         "grids": "node src/create-grid",
         "build": "esbuild src/bin/assign_geodata.js src/bin/generate_excel.js src/bin/generate_faces.js --bundle --platform=node --outdir=dist --external:canvas",
+        "test": "jest --verbose",
         "lint": "eslint .",
         "lint:fix": "eslint . --fix"
     },
+    "icon": "assets/logo.jpg",
     "bin": {
         "panos-geotag": "./dist/assign_geodata.js",
         "panos-excel": "./dist/generate_excel.js",
         "panos-faces": "./dist/generate_faces.js"
     },
     "files": [
-        "dist"
+        "dist",
+        "LICENSE",
+        "INSTALL",
+        "assets",
+        "README.md"
     ],
-    "keywords": [],
+    "keywords": [
+        "panorama",
+        "equirectangular",
+        "cubemap",
+        "360",
+        "geotag",
+        "exif",
+        "gps",
+        "krpano",
+        "tiles",
+        "cli"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/youmtinet-krpano/equirectongular-to-tiles.git"
+    },
+    "bugs": {
+        "url": "https://github.com/youmtinet-krpano/equirectongular-to-tiles/issues"
+    },
+    "homepage": "https://github.com/youmtinet-krpano/equirectongular-to-tiles#readme",
     "publisher": "YOUMTINET",
     "author": "Younes Mrabti <admin@youmti.net>",
-    "license": "ISC",
+    "license": "MIT",
+    "engines": {
+        "node": ">=16.0.0"
+    },
     "dependencies": {
         "canvas": "^2.11.2",
         "commander": "^14.0.0",
@@ -43,8 +71,9 @@
         "eslint-plugin-jest": "^28.5.0",
         "eslint-plugin-prettier": "^5.1.3",
         "eslint-plugin-security": "^3.0.0",
+        "jest": "^29.7.0",
         "lint-staged": "^15.2.2",
         "prettier": "^3.2.5"
     },
     "packageManager": "yarn@1.22.21+sha1.1959a18351b811cdeedbd484a8f86c3cc3bbaf72"
-}
+}