mapcachetools 2.2.4 → 2.3.0

package/README.md

@@ -2,15 +2,15 @@
 
 A robust Node.js tool to download map tiles (satellite or terrain RGB) for a specified geographic area and zoom range, storing them as PNG images in a folder. Ideal for offline map applications, such as integration with [Leaflet](https://leafletjs.com/) or 3D rendering projects like WebGL-based terrain visualization. Features include parallel downloads, retry handling, progress tracking, and support for multiple map providers.
 
+[View on npm](https://www.npmjs.com/package/mapcachetools)
 
 Watch a demo video showcasing the tool:  
 [![Watch the video](https://github.com/HefnySco/mapcache/blob/master/images/youtube.png?raw=true)](https://youtu.be/aSb6xNOQqok)
 
-
 ## Features
 
-- **Supported Providers**: OpenStreetMap (OSM), Mapbox Satellite, and Mapbox Terrain RGB (for elevation data).
-- **Unified PNG Format**: All tiles are saved as PNG, with Mapbox Satellite tiles converted from JPG for consistency.
+- **Supported Providers**: OpenStreetMap (OSM), Mapbox Satellite, Mapbox Terrain RGB (for elevation data), and Stadiamaps Satellite.
+- **Unified PNG Format**: All tiles are saved as PNG, with Mapbox Satellite and Stadiamaps tiles converted from JPG for consistency.
 - **Parallel Downloads**: Configurable concurrency to optimize speed while respecting provider rate limits.
 - **Retry Mechanism**: Automatically retries failed downloads (default: 3 attempts) with exponential backoff.
 - **Progress Tracking**: Displays real-time progress with percentage completion.
@@ -20,8 +20,20 @@ Watch a demo video showcasing the tool:
 
 ## Installation
 
+### Option 1: Run Directly via npx (No Install)
+Run the tool without a global install:
+
+```bash
+npx mapcachetools --help
+```
+
+Then run the tool with:
 
-### Option 1: Install Globally via npm
+```bash
+npx mapcachetools --lat1=<lat> --lng1=<lng> --lat2=<lat> --lng2=<lng> --zin=<max_zoom> --folder=<output_folder> [options]
+```
+
+### Option 2: Install Globally via npm
 Install the package globally to use the `mapcache-download` command from anywhere:
 
 ```bash
@@ -34,17 +46,24 @@ Then run the tool with:
 mapcache-download --lat1=<lat> --lng1=<lng> --lat2=<lat> --lng2=<lng> --zin=<max_zoom> --folder=<output_folder> [options]
 ```
 
-### Option 2: Clone and Install Locally
+### Option 3: Clone and Run Locally
 1. Clone the repository:
    ```bash
    git clone https://github.com/HefnySco/mapcache.git
    cd mapcache
    ```
 
-2. Install dependencies:
+2. Run using `npx` from this local folder:
    ```bash
-   npm install
+   npx --package . mapcachetools --help
    ```
+
+   Or run using Node directly:
+
+   ```bash
+   node ./bin/mapcache_download.js --help
+   ```
+
    Note: The `sharp` library is required for JPG-to-PNG conversion. Ensure system dependencies are installed:
    - Ubuntu/Debian: `sudo apt-get install libvips-dev`
    - macOS: `brew install libvips`
@@ -54,25 +73,43 @@ mapcache-download --lat1=<lat> --lng1=<lng> --lat2=<lat> --lng2=<lng> --zin=<max
 Download map tiles for a geographic area defined by two coordinates (`lat1,lng1` to `lat2,lng2`), a zoom range, and an output folder. Run the script with:
 
 ```bash
-node mapcache_download.js --lat1=<lat> --lng1=<lng> --lat2=<lat> --lng2=<lng> --zin=<max_zoom> --folder=<output_folder> [options]
+npx mapcachetools --lat1=<lat> --lng1=<lng> --lat2=<lat> --lng2=<lng> --zin=<max_zoom> --folder=<output_folder> [options]
+```
+
+If you cloned the repo and want to run from the local folder, use:
+
+```bash
+npx --package . mapcachetools --lat1=<lat> --lng1=<lng> --lat2=<lat> --lng2=<lng> --zin=<max_zoom> --folder=<output_folder> [options]
+```
+
+If you installed globally, use:
+
+```bash
+mapcache-download --lat1=<lat> --lng1=<lng> --lat2=<lat> --lng2=<lng> --zin=<max_zoom> --folder=<output_folder> [options]
 ```
 
 ### Example: Download OSM Tiles
 Download OpenStreetMap tiles for a small area with zoom levels 0 to 14:
 ```bash
-node mapcache_download.js --lat1=40.7128 --lng1=-74.0060 --lat2=40.7228 --lng2=-73.9960 --zin=14 --zout=0 --folder=./site/cachedMaps
+npx mapcachetools --lat1=40.7128 --lng1=-74.0060 --lat2=40.7228 --lng2=-73.9960 --zin=14 --zout=0 --folder=./site/cachedMaps
 ```
 
 ### Example: Download Mapbox Satellite Tiles
 Download Mapbox satellite tiles (saved as PNG, requires a Mapbox access token):
 ```bash
-node mapcache_download.js --lat1=40.7128 --lng1=-74.0060 --lat2=40.7228 --lng2=-73.9960 --zin=14 --folder=./site/cachedMaps --provider=1 --token=pk.eyJ1IjoibWhlZm55IiwiYSI6ImNrZW84Nm9rYTA2ZWgycm9mdmNscmFxYzcifQ.c-zxDjXCthXmRsErPzKhbQ
+npx mapcachetools --lat1=40.7128 --lng1=-74.0060 --lat2=40.7228 --lng2=-73.9960 --zin=14 --folder=./site/cachedMaps --provider=1 --token=pk.eyJ1IjoibWhlZm55IiwiYSI6ImNrZW84Nm9rYTA2ZWgycm9mdmNscmFxYzcifQ.c-zxDjXCthXmRsErPzKhbQ
 ```
 
 ### Example: Download Mapbox Terrain RGB Tiles
 Download Mapbox terrain RGB tiles for elevation data:
 ```bash
-node mapcache_download.js --lat1=40.7128 --lng1=-74.0060 --lat2=40.7228 --lng2=-73.9960 --zin=14 --folder=./site/cachedMaps --provider=2 --token=pk.eyJ1IjoibWhlZm55IiwiYSI6ImNrZW84Nm9rYTA2ZWgycm9mdmNscmFxYzcifQ.c-zxDjXCthXmRsErPzKhbQ
+npx mapcachetools --lat1=40.7128 --lng1=-74.0060 --lat2=40.7228 --lng2=-73.9960 --zin=14 --folder=./site/cachedMaps --provider=2 --token=pk.eyJ1IjoibWhlZm55IiwiYSI6ImNrZW84Nm9rYTA2ZWgycm9mdmNscmFxYzcifQ.c-zxDjXCthXmRsErPzKhbQ
+```
+
+### Example: Download Stadiamaps Satellite Tiles
+Download Stadiamaps satellite tiles (saved as PNG, requires a Stadiamaps API key):
+```bash
+npx mapcachetools --lat1=40.7128 --lng1=-74.0060 --lat2=40.7228 --lng2=-73.9960 --zin=14 --folder=./site/cachedMaps --provider=3 --token=<your-stadiamaps-api-key>
 ```
 
 ### Options
@@ -81,8 +118,8 @@ node mapcache_download.js --lat1=40.7128 --lng1=-74.0060 --lat2=40.7228 --lng2=-
 - `--zin`: Maximum zoom level (required, e.g., 18).
 - `--zout`: Minimum zoom level (default: 0).
 - `--folder`: Output folder for tiles (required, e.g., `./site/cachedMaps`).
-- `--provider`: Map provider (0=OSM, 1=Mapbox Satellite, 2=Mapbox Terrain RGB; default: 0).
-- `--token`: Mapbox access token (required for provider 1 or 2).
+- `--provider`: Map provider (0=OSM, 1=Mapbox Satellite, 2=Mapbox Terrain RGB, 3=Stadiamaps Satellite; default: 0).
+- `--token`: Mapbox or Stadiamaps access token (required for provider 1, 2, or 3).
 - `--concurrency`: Number of parallel downloads (default: 5).
 - `--retries`: Retry attempts for failed downloads (default: 3).
 - `--force`: Redownload existing files (default: false).
@@ -103,6 +140,7 @@ Access the tiles at `http://localhost:8080/cachedMaps`. The folder `./site/cache
 - OSM: `osm_<x>_<y>_<zoom>.png`
 - Mapbox Satellite: `sat_<x>_<y>_<zoom>.png`
 - Mapbox Terrain RGB: `terrain_<x>_<y>_<zoom>.png`
+- Stadiamaps Satellite: `stadiamaps_<x>_<y>_<zoom>.png`
 
 ## Integration with 3D Mapping Projects
 
@@ -121,18 +159,45 @@ Ensure the output folder matches your project's tile cache directory, and use th
 - **OpenStreetMap (OSM)**: Free, no token required. Tiles are natively PNG. [Website](https://www.openstreetmap.org/).
 - **Mapbox Satellite**: High-quality satellite imagery, converted from JPG to PNG for consistency. Requires a Mapbox access token. [Website](https://api.mapbox.com/).
 - **Mapbox Terrain RGB**: Elevation data encoded in RGB PNG tiles. Requires a Mapbox access token. [Website](https://docs.mapbox.com/data/tilesets/reference/mapbox-terrain-rgb-v1/).
+- **Stadiamaps Satellite**: High-quality satellite imagery, converted from JPG to PNG. Requires a Stadiamaps API key. [Website](https://stadiamaps.com/).
 
-Obtain a Mapbox token from [Mapbox Account](https://account.mapbox.com/).
+Obtain a Mapbox token from [Mapbox Account](https://account.mapbox.com/) or a Stadiamaps API key from [Stadiamaps Account](https://stadiamaps.com/).
 
 ## Notes
 
-- **Rate Limits**: Mapbox enforces rate limits (e.g., 750 requests/min for satellite, 200 for terrain RGB on free tiers). Adjust `--concurrency` to avoid being throttled.
+- **Rate Limits**: Mapbox and Stadiamaps enforce rate limits. Adjust `--concurrency` to avoid being throttled.
 - **File Overwrites**: Use `--force=true` to redownload tiles if they are outdated or corrupted.
-- **File Size**: Mapbox Satellite tiles are converted to PNG, which may increase file size compared to JPG. Consider disk space for large areas.
+- **File Size**: Mapbox Satellite and Stadiamaps tiles are converted to PNG, which may increase file size compared to JPG. Consider disk space for large areas.
 - **Tile Validation**: For critical applications, validate PNG tiles post-download to ensure integrity (e.g., using `sharp` metadata).
 
+## USE CASE
+
+  DroneEngage Airgap Server uses [MapCache](https://youtu.be/QivckjIQ9Sk) to cache map tiles for offline use in drone missions.
+   ![DroneEngage Airgap Server](https://cloud.ardupilot.org/_images/swarm-interface-view.png)
 
 ## Disclaimer
 
-Please review the terms and conditions of your chosen map provider (e.g., [OpenStreetMap](https://www.openstreetmap.org/copyright), [Mapbox](https://www.mapbox.com/tos)). The author assumes no liability for any incidental, consequential, or other damages arising from the use of this tool.
+Please review the terms and conditions of your chosen map provider (e.g., [OpenStreetMap](https://www.openstreetmap.org/copyright), [Mapbox](https://www.mapbox.com/tos), [Stadiamaps](https://stadiamaps.com/terms-of-service)). The author assumes no liability for any incidental, consequential, or other damages arising from the use of this tool.
+
+## Package Sidebar
+
+### Install
+
+`npm i mapcachetools`
+
+### Version
+
+2.2.6
+
+### License
+
+ISC
+
+### Unpacked Size
+
+22.7 kB
+
+### Total Files
+
+6
 

package/bin/mapcache_download.js

@@ -98,10 +98,11 @@ function fn_convertFromLngLatToPoints(lat1, lng1, lat2, lng2, zoom) {
   point2.x = Math.floor(point2.x / 256);
   point2.y = Math.floor(point2.y / 256);
 
-  // Ensure point1 is top-left, point2 bottom-right
-  if (point1.y > point2.y) [point1.y, point2.y] = [point2.y, point1.y];
-
-  return [point1, point2];
+  // Ensure point1 is top-left (min x, min y), point2 is bottom-right (max x, max y)
+  return [
+    { x: Math.min(point1.x, point2.x), y: Math.min(point1.y, point2.y) },
+    { x: Math.max(point1.x, point2.x), y: Math.max(point1.y, point2.y) }
+  ];
 }
 
 /* ============================================================
@@ -151,6 +152,7 @@ function getTileUrlAndFilename(i, j, zoom) {
     typePrefix = "terrain";
   } else if (map_provider == 3) {
     url = `https://tiles.stadiamaps.com/tiles/alidade_satellite/${zoom}/${i}/${j}.jpg?api_key=${TOKEN}`;
+    typePrefix = "stadiamaps";
   } else {
     // OpenStreetMap
     url = `https://tile.openstreetmap.org/${zoom}/${i}/${j}.png`;
@@ -268,7 +270,7 @@ function fn_handle_arguments() {
 
   // Provider and token
   map_provider = myArgs.provider ? parseInt(myArgs.provider) : DEFAULT_PROVIDER;
-  if (map_provider === 1 || map_provider === 2) {
+  if (map_provider === 1 || map_provider === 2 || map_provider === 3) {
     TOKEN = myArgs.token;
     if (!TOKEN) {
       error = true;

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "mapcachetools",
-  "version": "2.2.4",
+  "version": "2.3.0",
   "description": "A Node.js tool to download and cache map tiles (OSM, Mapbox Satellite, Mapbox Terrain RGB) as PNG images for offline use in mapping applications. Use at your own risk and comply with provider terms.",
   "main": "bin/mapcache_download.js",
   "bin": {
-    "mapcache-download": "./bin/mapcache_download.js"
+    "mapcache-download": "./bin/mapcache_download.js",
+    "mapcachetools": "./bin/mapcache_download.js"
   },
   "scripts": {
     "start": "node ./bin/mapcache_download.js",