update readme & other fixes

CONTRIBUTING.md

@@ -6,7 +6,7 @@ To get started:
 
 ```sh
 nvm use
-npm start
+npm run watch
 ```
 
 or so if you didn't create the `.env` file
@@ -27,6 +27,18 @@ For the final build:
 npm run build
 ```
 
+## Examples
+
+> [!NOTE]
+> For examples we use Carina Nebula image with copyrights from [webbtelescope.org](https://webbtelescope.org/contents/media/images/2022/031/01G77PKB8NKR7S8Z6HBXMYATGJ)
+
+Please run:
+
+- `npm run build # or watch`. This command will built this utility
+- `npm run examples:build`. This will load image and generate tiles
+- `npm run examples`. This will serve examples
+
+
 ## GitHub actions
 
 After you create a new tag, or just push changes to the server, ci will be launched

README.md

@@ -1,23 +1,72 @@
-# Tile generator CLI utility
+# Mappable Tile generator CLI utility
 
 [![npm version](https://badge.fury.io/js/@mappable-world/mappable-tiles-generator.svg)](https://badge.fury.io/js/@mappable-world/mappable-tiles-generator)
 [![npm](https://img.shields.io/npm/dm/@mappable-world/mappable-tiles-generator.svg)](https://www.npmjs.com/package/@mappable-world/mappable-tiles-generator)
+[![Build Status](https://github.com/mappable-world/mappable-tiles-generator/workflows/Run%20tests/badge.svg)](https://github.com/mappable-world/mappable-tiles-generator/actions/workflows/tests.yml)
 
-## How use
+This tool will help you in splitting a large image into smaller tiles for use on a [Mappable](https://mappable.world) map with accurate scale.
 
-The package is located in the `dist` folder:
+Your image will be scaled automatically for each level of zoom (scheme is presented below). At maximum zoom level, the image will show pixel-to-pixel detail. If you would like to see the image at a higher level of zoom, you can use the `maxZoom` option to enlarge it. Additionally, you can choose to restrict the minimum zoom level for tile generation by setting the `minZoom` option.
 
-- `dist/types` TypeScript types
-- `dist/esm` es6 modules for direct connection in your project
-- `dist/index.js` Mappable JS Module
+![tiling scheme](./tiling%20scheme.png)
 
-## Examples
+By default, we do not center the image and do not generate empty tiles. If you need it, specify the `shouldCenter` and `withEmptyTiles`` options respectively.
+
+The utility also generates a `params.json` file with presets for correct display of your image on a map. You can see an [example](./example/vanilla.html) of using this utility with [@mappable-world/mappable-cartesian-projection](https://github.com/mappable-world/mappable-cartesian-projection) package.
 
 > [!NOTE]
-> For examples we use Carina Nebula image with copyrights from [webbtelescope.org](https://webbtelescope.org/contents/media/images/2022/031/01G77PKB8NKR7S8Z6HBXMYATGJ)
+> For more information on how to run the examples locally, please see the [CONTRIBUTING.md](./CONTRIBUTING.md#examples)
+
+## Install
+
+Install Tile generator CLI to be used in your project with
+
+```bash
+npm install --save-dev @mappable-world/mappable-tiles-generator
+```
+
+And then you should be able to run the CLI with
+
+```bash
+npx mappable-tiles-generator --help
+```
+
+## Usage
+
+You can use it via terminal:
+
+```bash
+Options:
+  -s, --source, --src                  Source image path     [string] [required]
+  -d, --destination, --dst             Destination tiles folder path
+                                                   [string] [default: "./tiles"]
+      --pathTemplate, --path           Template pathname for the generated tile
+                                       files
+                                     [string] [default: "{{z}}/{{y}}-{{x}}.png"]
+      --minZoom, --min                 Minimum zoom level for tile generation
+                                                                        [number]
+      --maxZoom, --max                 Maximum zoom level for tile generation
+                                                                        [number]
+      --tileSize, --size               Width and height tile size
+                                                         [number] [default: 256]
+  -c, --shouldCenter, --center         Should center image be in tail grid
+                                                      [boolean] [default: false]
+  -e, --withEmptyTiles, --emptyTiles   Should generate background empty tiles
+                                       around the image
+                                                      [boolean] [default: false]
+  -b, --backgroundColor, --background  Background color for completely or
+                                       partially empty tiles
+                                                 [string] [default: "#00000000"]
+  -v, --version                        Show version number             [boolean]
+  -h, --help                           Show help                       [boolean]
+
+License: Apache-2
+```
+
+Or you can also use it in code:
 
-Please run:
+```js
+import {generateTiles} from '@mappable-world/mappable-tiles-generator';
 
-- `npm run build # or watch`. This command will built this utility
-- `npm run examples:build`. This will load image and generate tiles
-- `npm run examples`. This will serve examples
+generateTiles(source, destination, {shouldCenter: true});
+```

package.json

@@ -2,23 +2,22 @@
     "version": "0.0.1-beta.1",
     "name": "@mappable-world/mappable-tiles-generator",
     "description": "Mappable Maps JS API 3.0 Tile generator CLI utility",
-    "types": "./dist/types/index.d.ts",
-    "main": "./dist/esm/index.js",
+    "types": "./dist/index.d.ts",
+    "main": "./dist/index.js",
     "scripts": {
         "test": "jest",
         "lint": "eslint ./",
         "build": "rm -rf ./dist && tsc --project tsconfig.build.json",
         "watch": "npm run build -- --watch",
         "examples:image:load": "curl 'https://stsci-opo.org/STScI-01GA6KKWG229B16K4Q38CH3BXS.png' > example/image.png",
-        "examples:tiles:gererate": "node dist/index.js --s example/image.png --d example/tiles",
+        "examples:tiles:gererate": "rm -rf example/tiles && node dist/index.js --s example/image.png --d example/tiles",
         "examples:build": "npm run examples:image:load && npm run examples:tiles:gererate",
         "examples": "webpack serve",
         "bump": "npm version prerelease --preid=beta --no-git-tag-version && npm run bump:git",
         "bump:git": "git add --all && git commit -m \"New version $npm_package_version\" && git tag $npm_package_version && git push --tags origin HEAD:main"
     },
     "devDependencies": {
         "@mappable-world/mappable-cli": "^0.0.19",
-        "@mappable-world/mappable-types": "^0.0.10",
         "@types/got": "9.6.12",
         "@types/jest": "29.5.3",
         "@types/jsdom": "21.1.1",
@@ -41,11 +40,12 @@
         "webpack-dev-server": "4.15.1"
     },
     "dependencies": {
+        "@mappable-world/mappable-types": "^0.0.10",
         "jimp": "0.22.10",
         "yargs": "17.7.2"
     },
     "license": "Apache-2",
     "bin": {
-        "mappable-cli": "./dist/index.js"
-      }
+        "mappable-tiles-generator": "./dist/index.js"
+    }
 }

src/argv.ts

@@ -1,5 +1,4 @@
 import * as yargs from 'yargs';
-import * as path from 'path';
 
 export const argv = yargs
     .strict()
@@ -13,51 +12,57 @@ export const argv = yargs
         type: 'string',
         alias: ['dst', 'd'],
         demandOption: false,
-        default: path.join(process.cwd(), 'tiles'),
+        default: './tiles',
         description: 'Destination tiles folder path'
     })
     .option('pathTemplate', {
         type: 'string',
         alias: 'path',
         demandOption: false,
         default: '{{z}}/{{y}}-{{x}}.png',
-        description: 'Destination tiles folder path'
+        description: 'Template pathname for the generated tile files'
     })
     .option('minZoom', {
         type: 'number',
         alias: 'min',
         demandOption: false,
-        default: undefined
+        default: undefined,
+        description: 'Minimum zoom level for tile generation'
     })
     .option('maxZoom', {
         type: 'number',
         alias: 'max',
         demandOption: false,
-        default: undefined
+        default: undefined,
+        description: 'Maximum zoom level for tile generation'
     })
     .option('tileSize', {
         type: 'number',
         alias: 'size',
         demandOption: false,
-        default: 256
+        default: 256,
+        description: 'Width and height tile size'
     })
     .option('shouldCenter', {
         type: 'boolean',
         alias: ['center', 'c'],
         demandOption: false,
-        default: false
+        default: false,
+        description: 'Should center image be in tail grid'
     })
     .option('withEmptyTiles', {
         type: 'boolean',
         alias: ['emptyTiles', 'e'],
         demandOption: false,
-        default: false
+        default: false,
+        description: 'Should generate background empty tiles around the image'
     })
     .option('backgroundColor', {
         type: 'string',
         alias: ['background', 'b'],
         demandOption: false,
-        default: '#00000000'
+        default: '#00000000',
+        description: 'Background color for completely or partially empty tiles'
     })
     .version(require('../package').version)
     .alias('version', 'v')

src/index.ts

@@ -1,12 +1,16 @@
+#! /usr/bin/env node
+
 import * as tilegen from './tilegen';
 import {argv} from './argv';
 
 if (require.main === module) {
     const options: tilegen.GenerationOptions = {
         zoomRange: {},
+        backgroundColor: argv.backgroundColor,
+        pathTemplate: argv.pathTemplate,
         shouldCenter: argv.shouldCenter,
-        withEmptyTiles: argv.withEmptyTiles,
-        pathTemplate: argv.pathTemplate
+        tileSize: argv.tileSize,
+        withEmptyTiles: argv.withEmptyTiles
     };
 
     if (argv.minZoom) {

src/tilegen.ts

@@ -1,7 +1,7 @@
+import type {GenericBounds, MMapProps, MapMode, WorldOptions, ZoomRange} from '@mappable-world/mappable-types';
 import fs from 'node:fs';
 import path from 'node:path';
 import Jimp from 'jimp';
-import type {GenericBounds, MMapProps, MapMode, WorldOptions, ZoomRange} from '@mappable-world/mappable-types';
 
 export interface GenerationOptions {
     tileSize?: number;
@@ -31,9 +31,6 @@ export async function generateTiles(source: string, destination: string, options
     const {tileSize, shouldCenter, withEmptyTiles, pathTemplate, backgroundColor} = computedOptions;
     let image = await Jimp.read(source);
 
-    await fs.promises.rm(destination, {recursive: true, force: true, maxRetries: 1});
-    await fs.promises.mkdir(destination);
-
     const maxImageZoom = Math.ceil(Math.log2(Math.max(image.getWidth(), image.getHeight()) / tileSize));
     const zoomRange = {
         min: computedOptions.zoomRange.min ?? 0,
@@ -43,11 +40,8 @@ export async function generateTiles(source: string, destination: string, options
     const maxZoomImage = await getMaxZoomImage(image, {zoomRange, tileSize, maxImageZoom, shouldCenter, backgroundColor});
 
     const imageSize: ImageSize = {width: image.getWidth(), height: image.getHeight()};
-    const params = getParams({imageSize, shouldCenter, maxImageZoom, zoomRange, tileSize, pathTemplate});
 
-    const filePromises: Promise<unknown>[] = [
-        fs.promises.writeFile(path.join(destination, 'params.json'), JSON.stringify(params, null, 4))
-    ];
+    const filePromises: Promise<unknown>[] = [];
     const tileBackground = await Jimp.create(tileSize, tileSize, backgroundColor);
 
     for (let zoom = zoomRange.max; zoom >= zoomRange.min; zoom--) {
@@ -83,6 +77,9 @@ export async function generateTiles(source: string, destination: string, options
         }
     }
 
+    const params = getParams({imageSize, shouldCenter, maxImageZoom, zoomRange, tileSize, pathTemplate});
+    filePromises.push(fs.promises.writeFile(path.join(destination, 'params.json'), JSON.stringify(params, null, 4)));
+
     await Promise.all(filePromises);
 }