From 5a4adcbbff15857a6f4c315d54280d542f785fec Mon Sep 17 00:00:00 2001 From: Wentao Kuang Date: Fri, 27 Oct 2023 17:02:41 +1300 Subject: [PATCH] feat(doc): Improve the individual package documentations. BM-776 (#2981) #### Motivation Tidy up individual READMEs, make sure text is up-to-date #### Modification - Review and rewrite all the individual READMES. - Link through to package READMEs from main README #### Checklist - [ ] Tests updated - [x] Docs updated - [ ] Issue linked in Title --------- Co-authored-by: Blayne Chard --- README.md | 23 +++++ packages/__tests__/README.md | 2 +- packages/_infra/README.md | 39 +++++---- packages/attribution/README.md | 2 +- packages/bathymetry/README.md | 7 +- packages/bathymetry/tsconfig.json | 2 +- packages/cli/README.md | 118 +++---------------------- packages/config/README.md | 128 +++++++++++++++++++++++++--- packages/geo/README.md | 26 +++--- packages/lambda-analytics/README.md | 58 ++++++------- packages/lambda-tiler/README.md | 94 +++++++++++++++++++- packages/landing/README.md | 2 - packages/linzjs-geojson/README.md | 8 +- packages/server/README.md | 10 +-- packages/smoke/README.md | 2 +- packages/sprites/README.md | 2 +- packages/tiler-sharp/README.md | 12 +++ packages/tiler/README.md | 11 ++- 18 files changed, 339 insertions(+), 207 deletions(-) create mode 100644 packages/tiler-sharp/README.md diff --git a/README.md b/README.md index fb321b385..abf5b199c 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,29 @@ A digital basemap provides a consistent background detail necessary to orient location and add to aesthetic appeal. Basemaps can be made up of streets, parcels, boundaries (country, regional, and city boundaries), shaded relief of a digital elevation model, waterways, hydrography, aerial and satellite imagery. Basemaps can be used as desktop, website or mobile phone application components, or as a 3rd party layers within a GIS or desktop mapping application. +## Packages: + +- [@basemaps/test](packages/__tests__/) - Testing utilities and assets +- [@basemaps/infra](packages/_infra/) - Infrastructure code using [AWS CDK](https://github.com/aws/aws-cdk) +- [@basemaps/attribution](packages/attribution/) - Calculate the attribution for given map location +- [@basemaps/bathymetry](packages/bathymetry/) - Convert bathymetry from [GEBCO](https://www.gebco.net/) into colorized HillShade geotiff. +- [@basemaps/cli](packages/cli/) - cli that using for CICD process +- [@basemaps/cogify](packages/cogify/) - CLI to re-tile imagery into a Cloud Optimised Geotiffs (COG) +- [@basemaps/config](packages/config/) - Configurations for Basemaps system +- [@basemaps/geo](packages/geo/) - Utility to work with QuadKeys, Tiles and Projections. +- [@basemaps/lambda-analytics](packages/lambda-analytics/) - Generate analytics from CloudFront distribution statistics +- [@basemaps/lambda-tiler](packages/lambda-tiler/) - Lambda server for WMTS/XYZ map generation +- [@basemaps/landing](packages/landing/) - The landing page for Basemaps +- [@basemaps/server](packages/server/) - cli for WMTS/XYZ Tile server +- [@basemaps/shared](packages/shared/) - Shared Utilities for other Basemaps packages +- [@basemaps/smoke](packages/smoke/) - Smoke tests +- [@basemaps/sprites](packages/sprites/) - sprite sheet generation +- [@basemaps/tiler](packages/tiler/) - Compose CogGeoTiffs for xyz tile server +- [@basemaps/tiler-sharp](packages/tiler-sharp/) - Generate tiles by using [sharp](https://github.com/lovell/sharp) and [libvips](https://github.com/libvips/libvips) +- [@linzjs/docker-command](packages/linzjs-docker-command/) - Utilities for running commands inside Docker +- [@linzjs/geojson](packages/linzjs-geojson/) - Utility for working with GeoJSON +- [@linzjs/metrics](packages/linzjs-metrics/) - Simple timing metric tracker for NodeJS + ## Building This repository requires [NodeJs](https://nodejs.org/en/) > 16 & [Yarn](https://yarnpkg.com/en/) diff --git a/packages/__tests__/README.md b/packages/__tests__/README.md index beba6807b..05466b3f6 100644 --- a/packages/__tests__/README.md +++ b/packages/__tests__/README.md @@ -1,6 +1,6 @@ # @basemaps/test -Testing utlities and assets +Testing utilities and assets ## Approx equal diff --git a/packages/_infra/README.md b/packages/_infra/README.md index a22908c25..4402b28db 100644 --- a/packages/_infra/README.md +++ b/packages/_infra/README.md @@ -1,24 +1,23 @@ # @basemaps/infra -Using AWS CDK to deploy and manage the infrastructure for basemaps +Infrastructure code that using [AWS CDK](https://github.com/aws/aws-cdk) to deploy and manage the AWS infrastructure for Basemaps ## Stacks -There are three stacks used for this system +There are three following stacks used for Basemaps system ### Table -API Key table, this dynamodb table is shared across stacks so it is deployed as a sperate stack. -It is used to track api key usage - -### Edge - -This is the edge of the tile serving, it is the egress point for all tiles. It deploys a CloudFront distribution with a lambda function that validates API Keys against the API Key Table +`TileMetadataTable` table, this dynamodb table is shared across stacks so it is deployed as a separated stack. +It is used to save the Metadata of the Basemaps configurations in the [@basemaps/config](../config/). ### Serve -The core tile generation service, this service generates the tiles and serves them via a application load balancer which is connected to Edge +The core tile generation service for [@basemaps/lambda-tiler](../lambda-tiler/) APIs, this service generates the tiles and serves them via a lambda URL which is connected to Edge CDN +### Edge + +This is the edge of the tile serving, it is the egress point for all tiles. ## Usage @@ -26,14 +25,12 @@ The infrastructure needs a number of environment variables to run ```javascript // The accountId that will be used to deploy into -CDK_DEFAULT_ACCOUNT +CDK_DEFAULT_ACCOUNT; -// Due to the convoluted way that TLS certificates are made inside LINZ a hard coded TLS ARN is needed for the load balancer and Cloudfront -ALB_CERTIFICATE_ARN -CLOUDFRONT_CERTIFICATE_ARN +// Due to the convoluted way that TLS certificates are made inside LINZ a hard coded TLS ARN is needed for the Cloudfront +CLOUDFRONT_CERTIFICATE_ARN; ``` - For first usage you will need to bootstrap the account, this will create a s3 bucket to store CDK assets in ```bash @@ -43,5 +40,17 @@ npx cdk bootstrap To create a CloudFormation template ```bash -cdk synth +npx cdk synth +``` + +To list all the available stacks + +```bash +npx cdk list +``` + +To deploy `ServeStack` stack + +```bash +npx cdk deploy ServeStack ``` diff --git a/packages/attribution/README.md b/packages/attribution/README.md index 027aa5fe1..8ce7c49e2 100644 --- a/packages/attribution/README.md +++ b/packages/attribution/README.md @@ -8,7 +8,7 @@ Library to determine to applicable attribution for a given extent and zoom level npm install @basemaps/attribution ``` -```js +```typescript import { Attribution } from '@basemaps/attribution'; const attributions = await Attribution.load('https://basemaps.linz.govt.nz/v1/tiles/aerial/EPSG:3857/attribution.json?api=...'); diff --git a/packages/bathymetry/README.md b/packages/bathymetry/README.md index 183229d8a..40ee6842c 100644 --- a/packages/bathymetry/README.md +++ b/packages/bathymetry/README.md @@ -1,11 +1,11 @@ -# Bathymetry creation +# @basemaps/bathymetry +## Bathymetry creation This process takes batheymetric data from [GEBCO](https://www.gebco.net/) and converts it into a colorized hillshaded geotiff. ![](./images/bathyoutput.png) - ## Usage You will need: @@ -18,7 +18,7 @@ You will need: # Install dependencies yarn add @basemaps/bathymetry -# To prevent very long CI/Dev build times, mapnik will need to be manually installed +# To prevent very long CI/Dev build times, mapnik will need to be manually installed yarn add mapnik # Ensure the javascript has been built @@ -28,7 +28,6 @@ yarn build node build/index.js -v create --input gebco_2020.nc --docker --output gebco/ ``` - ## Process ![](./images/bathyprocess.png) diff --git a/packages/bathymetry/tsconfig.json b/packages/bathymetry/tsconfig.json index 2f4ed62be..63f077f60 100644 --- a/packages/bathymetry/tsconfig.json +++ b/packages/bathymetry/tsconfig.json @@ -4,6 +4,6 @@ "rootDir": "./src", "outDir": "./build" }, - "include": ["src/**/*"], + "include": [".src/**/*"], "references": [{ "path": "../__tests__" }, { "path": "../shared" }, { "path": "../cli" }] } diff --git a/packages/cli/README.md b/packages/cli/README.md index 2d1cda66e..7ef63ffad 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -1,6 +1,6 @@ # @basemaps/cli -CreateThis package is to control the configuration in the LINZ basemaps product. +This package contains cli's that are mainly used by the configuration and CICD processes in the LINZ Basemaps. All of the cli commands in this package will be build into docker container and publish as a [github container](https://github.com/linz/basemaps/pkgs/container/basemaps%2Fcli) ## Install @@ -14,130 +14,32 @@ npm i @basemaps/cli ## Usage -- Bundle -Bundle config files into config bundle json from a given config path. +Bundle config files into config bundle json from a given config path. This is mainly use for [linz/basemaps-config](https://github.com/linz/basemaps-config) CICD process to bundle all the individual config json files into a single JSON bundle. ```bash -./bin/bmc.js bundle --config config/ --output config.json +./bin/bmc.js bundle --config config/ --assets assets/asset.tar --output config.json ``` ## Usage -- Import -Import all configs from a bundled config.json into dynamo db from a given config path +Import all configs from a bundled config.json into dynamo db from a given config path. This is mainly use for [linz/basemaps-config](https://github.com/linz/basemaps-config) repository ci/cd process to deploy the config changes into DynamoDB. ```bash ./bin/bmc.js import --config config.json --commit ``` -## Usage -- Screenshots +## Usage -- Create Config -Dump the screenshots from basemaps production +Create a individual config.json from a path of imagery for Basemaps to load as standalone server to view them. This is mainly used for the preview images for the Basemaps imagery import process. ```bash -./bin/bmc.js screenshot +./bin/bmc.js create-config --path s3://..../images/*.tiff --title image_title --commit ``` -Dump the screenshots from different host +## Usage -- Overview -```bash -./bin/bmc.js screenshot --host HOST - -``` - -Dump the screenshots with config file - -```bash -./bin/bmc.js screenshot --config s3://..../config.json.gz - -``` - -## Usage -- sprites - -Generate a sprite sheet from a list of sprites - -``` -./bin/bmc.js sprites --ratio 1 --ratio 2 --path ./config/sprites/topographic --output assets -``` - -Outputs: - -assets/topographic.json -assets/topographic.png - -assets/topographic@2x.json -assets/topographic@2x.png - -## Usage -- cogify - -Create a collection of cloud optimized geotiff's from a collection of geotiff, that is optimized to be used in `@basemaps/tiler` - -Create a list of COG's to create - -```bash -./bin/bmc.js -V job --source ./source_folder/ --output ./source_folder/cogify/ -``` - -Build a specific COG - -```bash -./bin/bmc.js -V cog --job ./cogs/01DYREBEEFFXEPBAYBED2TMAFJ/job.json --name 1-2-3 --commit -``` - -Make cog job json +Create a overview tar file of tiles from the given of imagery. This create low zoom level tiles for the individual imagery and significantly improve the performance of serving individual imagery by pre-rendering and saving the tiles instead of rendering them on the fly. ```bash -./bin/bmc.js -V make-cog --imagery s3://imagery_path --target destination_bucket --name imagery_name --tile-matrix NZTM2000Quad --output ./jobs.json +./bin/bmc.js create-overview --config s3://..../images/*.tiff --output overview/overviews.tar.co ``` - -Split make cog job into chunked sub-jobs - -```bash -./bin/bmc.js -V split-job --job s3://imagery_path/job.json --output jobs.json -``` - -## Advanced Job creation - -Useful configuration options for `cogify job` - -### Min Tile zoom `--min-zoom :number` - -using the argument `--min-zoom` will configure the highest COG tile that can be created -for example, `--min-zoom 10` means tiles of zoom `0 - 10` can be created but `11` cannot. - -This is useful to control the size of COGS across varying imagery sets World level z0-5 vs region z12-15 vs specific area 20+ - -### Concurrency `--concurrency :number` - -To load metadata quickly from S3 a lot of actions are run concurrently. using `--concurrent` controls the number of requests that can be outstanding at one time. - -### Max COGs `--max-cogs :number` - -Controls the number of output COGs to create for small imagery sets (<50GB) this number should be low < 5 for larger imagery sets this number can be much larger (100+ for TB+ imagery sets) - -### GeoJson `--geojson` - -Outputs two GeoJSON files to provide a representation of the source and target imagery, this can be used to help tune the generation parameters - -## Building a COG collection - -The best way to build a cog collection is to create multiple JOBS with `--geojson` enabled while adjusting `--max-cogs` and `--min-zoom` when a good covering is found the job can then be submitted to AWS for processing. - -Using a large area of interest as shown in the imagery set below and is showing three different sets of parameters, The shaded green area is the original source imagery - -![Example Covering](./static/example-covering.png) - -### Green outline - -**Arguments:** `--max-cogs 5 --min-zoom 15` -This has too much empty space inside the tile areas and is not a good example of a good collection of COGs to make. - -### Red outline - -**Arguments:** `--max-cogs 500 --min-zoom 25` - -This creates too many tiles with many only including one or two source images. - -### Blue outline - -**Arguments:** `--max-cogs 70 --min-zoom 20` - -This creates a decent covering without wasting too much space and not creating large area's of empty COG diff --git a/packages/config/README.md b/packages/config/README.md index bdb9d486c..0ec18490a 100644 --- a/packages/config/README.md +++ b/packages/config/README.md @@ -1,21 +1,24 @@ -# Basemaps Configuration - @basemaps/config +# @basemaps/config + +## Basemaps Configuration To effectively serve tiles to users, all rendering processes must be kept in synch with the exact same configuration. -Basemaps's stores its configuration into a single DyanmoDB table and separates the configuration objects into +Basemaps stores its configuration into a single DynamoDB table and separates the configuration objects into -- Imagery - Configuration for a single imagery layer, including location of all the Cloud optimised geotiffs, bouding boxes and +- Imagery - Configuration for a single imagery layer, including location of all the Cloud optimized geotiffs, bounding boxes - Tile Sets - Configuration on how to merge imagery/vector layers together to serve out as a combined layer - Style - Vector tile style configuration (Style.json) - Provider - Configuration about the owner of the service -This configuration is generally stored as JSON files in a git repository to allow easy modification and then programmatically loaded into basemaps's dynamodb table +This configuration is generally stored as JSON files in a git repository (eg [linz/basemaps-config](https://github.com/linz/basemaps-config) ) to allow easy modification and then programmatically loaded into Basemaps DynamoDB table For LINZ's implementation of this configuration see [linz/basemaps-config](https://github.com/linz/basemaps-config) -# Imagery Example +## Imagery Example [ConfigImagery](./src/config/imagery) + ```json { "v": 1, @@ -24,12 +27,113 @@ For LINZ's implementation of this configuration see [linz/basemaps-config](https "projection": 3857, "uri": "s3://linz-basemaps/3857/new_zealand_sentinel_2018-19_10m/01E8121FN71M0PNZ6VB87DW05Z", "year": 2018, - "files": [{ - "height": 4892, - "name": "13-8032-5113", - "width": 4892, - "x": 19254793.17314903, - "y": -4980025.266835816 - }] + "files": [ + { + "height": 4892, + "name": "13-8032-5113", + "width": 4892, + "x": 19254793.17314903, + "y": -4980025.266835816 + } + ] +} +``` + +## Tile Sets Example + +[ConfigTileSet](./src/config/tile.set.ts) + +```json +{ + "id": "ts_01H8JF29R6S2NT7QXNC7GK90D4", + "type": "raster", + "format": "webp", + "name": "manawatu-whanganui-sn9158-1991-0.375m", + "title": "Manawatū-Whanganui 0.375m SN9158 (1991)", + "layers": [ + { + "2193": "im_01H8JF29R6S2NT7QXNC7GK90D4", + "maxZoom": 32, + "minZoom": 0, + "name": "manawatu-whanganui-sn9158-1991-0.375m", + "title": "Manawatū-Whanganui 0.375m SN9158 (1991)" + } + ] +} +``` + +## Style Example + +[ConfigVectorStyle](./src/config/vector.style.ts) + +```json +{ + "id": "st_topographic", + "name": "topographic", + "style": { + "id": "st_topographic", + "glyphs": "/v1/fonts/{fontstack}/{range}.pbf", + "layers": [ + { + "id": "Background", + "filter": ["all", ["==", "class", "dock"]], + "layout": { + "visibility": "visible" + }, + "minzoom": 0, + "paint": { + "background-color": "rgba(184, 220, 242, 1)" + }, + "type": "background" + }, + { + "id": "Landcover-Sand", + "filter": ["all", ["==", "class", "sand"]], + "layout": { + "visibility": "visible" + }, + "minzoom": 8, + "paint": { + "fill-color": "rgba(226, 226, 226, 0.75)" + }, + "source": "LINZ Basemaps", + "source-layer": "landcover", + "type": "fill" + } + ] + } +} +``` + +## Provider Example + +[ConfigProvider](./src/config/provider.ts) + +```json +{ + "id": "pv_linz", + "name": "linz", + "serviceIdentification": { + "accessConstraints": "Basemap @ CC BY 4.0 Land Information New Zealand", + "description": "National map tile service provided by Land Information New Zealand", + "fees": "There are no fees associated with access via the web interface or API.", + "title": "LINZ Basemaps Service" + }, + "serviceProvider": { + "contact": { + "address": { + "city": "Wellington", + "country": "New Zealand", + "deliveryPoint": "Land Information New Zealand", + "email": "basemaps@linz.govt.nz", + "postalCode": "6145" + }, + "individualName": "LINZ Customer Support", + "phone": "+64 4 4600110", + "position": "Customer Support" + }, + "name": "Land Information New Zealand", + "site": "http://www.linz.govt.nz" + } } ``` diff --git a/packages/geo/README.md b/packages/geo/README.md index 5a6df165e..601b54312 100644 --- a/packages/geo/README.md +++ b/packages/geo/README.md @@ -12,13 +12,13 @@ const boundsB = new Bounds(0, 0, 256, 256); bounds.intersects(boundsB); // true -bounds.intersection(boundsB) // { x: 128, y: 128, width: 128, height: 128} +bounds.intersection(boundsB); // { x: 128, y: 128, width: 128, height: 128} ``` ## Typing for generic point and sizes ```typescript -import { Point, Size, BoundingBox } from '@basemaps/geo' +import { Point, Size, BoundingBox } from '@basemaps/geo'; const p: Point = { x: 5, y: 5 }; const s: Size = { width: 200, height: 500 }; @@ -38,27 +38,23 @@ QuadKey.fromTile({ x: 3, y: 2, z: 2 } // '31' ## Tile Matrix Sets - ```typescript -import {GoogleTms} from '@basemaps/geo/build/tms/google' - +import { GoogleTms } from '@basemaps/geo/build/tms/google'; /** Convert tile offsets into pixel coordinates */ -GoogleTms.tileToPixels(1, 1) // { x: 256, y: 256 } +GoogleTms.tileToPixels(1, 1); // { x: 256, y: 256 } /** Convert a tile into the upper left point in Google */ -GoogleTms.tileToSource({ x: 0, y: 0, z: 0 }) // { x: -20037508.3427892, y: 20037508.3427892 } +GoogleTms.tileToSource({ x: 0, y: 0, z: 0 }); // { x: -20037508.3427892, y: 20037508.3427892 } ``` - ## Epsg Helpers ```typescript -import {Epsg} from '@basemaps/geo' +import { Epsg } from '@basemaps/geo'; - -Epsg.Google.toEpsgCode() // `EPSG:3857` -Epsg.Google.toUrn() // `urn:ogc:def:crs:EPSG:3857` -Epsg.parse('3857') // Epsg.Google -Epsg.get(3857) // Epsg.Google -``` \ No newline at end of file +Epsg.Google.toEpsgCode(); // `EPSG:3857` +Epsg.Google.toUrn(); // `urn:ogc:def:crs:EPSG:3857` +Epsg.parse('3857'); // Epsg.Google +Epsg.get(3857); // Epsg.Google +``` diff --git a/packages/lambda-analytics/README.md b/packages/lambda-analytics/README.md index fc017008e..1fd1cca7c 100644 --- a/packages/lambda-analytics/README.md +++ b/packages/lambda-analytics/README.md @@ -1,40 +1,38 @@ # @basemaps/lambda-analytics - Generate analytics from CloudFront distribution statistics Every hour this lambda function runs and generates a rolled up summary of usage by API Key The analytics generated are grouped by API key and the following data is calculated + ```typescript export interface TileRequestStats { - /** Time of the rollup */ - timestamp: string; - /** Api Key used */ - api: string; - /** Type of api key (first character generally `c` for client generated or `d` for developer) */ - apiType: string; - /** Total number of hits */ - total: 0; - /** Cache stats as given by cloudfront */ - cache: { hit: 0; miss: 0 }; - /** Status codes given by cloudfront */ - status: Record; - /** Tile exensions used */ - extension: { webp: 0; jpeg: 0; png: 0; wmts: 0; other: 0 }; - /** Projections used */ - tileMatrix: { NZTM2000Quad: number, WebMercatorQuad: number, NZTM2000Old: number }, - /** Tilesets accessed */ - tileSet: Record; - /** How was this rollup generated */ - generated: { - timestamp: string; - /** Rollup version */ - v: number; - /** Git commit hash used */ - hash?: string; - /** Git Version used */ - version?: string - }; + /** Unique Id for the time range */ + statId: string; + /** Time of the rollup */ + timestamp: string; + /** Api Key used */ + api: string; + /** Referral uri */ + referer: string | undefined; + /** Type of api key (first character generally `c` for client generated or `d` for developer) */ + apiType: string; + /** Total number of hits */ + total: number; + /** Cache stats as given by cloudfront */ + cache: { hit: number; miss: number }; + /** Status codes given by cloudfront */ + status: Record; + /** Tile file extensions used */ + extension: { webp: number; jpeg: number; png: number; wmts: number; pbf: number; other: number }; + /** Tile Matrixes used */ + tileMatrix: Record; + /** Tilesets accessed */ + tileSet: Record; + /** Rough approximation of useragent user */ + userAgent: Record; + /** How was this rollup generated */ + generated: { v: number; hash?: string; version?: string }; } -``` \ No newline at end of file +``` diff --git a/packages/lambda-tiler/README.md b/packages/lambda-tiler/README.md index 6bf10aaaa..ddeae2fed 100644 --- a/packages/lambda-tiler/README.md +++ b/packages/lambda-tiler/README.md @@ -1,3 +1,95 @@ # @basemaps/lambda-tiler -XYZ interface for map generation +Lambda server for xyz map generation to provide apis for serving both raster and vector map. + +## APIs + +All available APIs are defined in the [index.ts](./src/index.ts) + +`Host: https://basemaps.linz.govt.nz/` + +### Server APIs + +Validate the server status, health, version which is using for the ci/cd. + +- GET [/ping](./src/routes/ping.ts) +- GET [/v1/ping](./src/routes/ping.ts) +- GET [/version](./src/routes/version.ts) +- GET [/v1/version](./src/routes/version.ts) +- GET [/health](./src/routes/health.ts) +- GET [/v1/health](./src/routes/health.ts) + +### xyz tile generation API + +Get a tile from the xyz and format for map generation, support both vector and raster tileSet. + +- GET [/v1/tiles/:tileSet/:tileMatrix/:z/:x/:y.:tileType](./src/routes/tile.xyz.ts) + +Example: + +``` +/v1/tiles/topographic/WebMercatorQuad/2/1/1.pbf - Vector Tile +/v1/tiles/aerial/WebMercatorQuad/6/0/38.webp - Raster Tile +``` + +### Imagery Metadata API + +Fetch the imagery metadata based on the imageryId + +- GET [/v1/imagery/:imageryId/:fileName](./src/routes/imagery.ts) + +Examples: + +``` +/v1/imagery/:imageryId/source.geojson - Source boudning boxes +/v1/imagery/:imageryId/covering.geojson - Output tile bounding boxes +/v1/imagery/:imageryId/cutline.geojson - Cutline used ont he imagery set +/v1/imagery/:imageryId/collection.json - STAC Collection +/v1/imagery/:imageryId/15-32659-21603.json - STAC Item +``` + +### Config APIs + +Fetch the imagery and tile set configurations + +- GET [/v1/config/:tileSet.json](./src/routes/config.ts) +- GET [/v1/config/:tileSet/:imageryId.json](./src/routes/config.ts) + +### Sprite and Fonts APIs + +To get the fonts and sprites for the vector map. + +- GET [/v1/sprites/:spriteName](./src/routes/sprites.ts) +- GET [/v1/fonts.json](./src/routes/fonts.ts) +- GET [/v1/fonts/:fontStack/:range.pbf](./src/routes/fonts.ts) + +### StyleJSON and TileJSON APIs + +Get the style json and tile json for the vector map. + +- GET [/v1/styles/:styleName.json](./src/routes/tile.style.json.ts) +- GET [/v1/tiles/:tileSet/:tileMatrix/tile.json](./src/routes/tile.json.ts) + +### Preview APIs + +Serve a preview of a imagery set + +- GET [/v1/preview/:tileSet/:tileMatrix/:z/:lon/:lat](./src/routes/preview.ts) +- GET [/v1/@:location](./src/routes/preview.index.ts) +- GET [/@:location](./src/routes/preview.index.ts) + +### Attribution APIs + +Get attribution json for the map attributions. + +- GET [/v1/tiles/:tileSet/:tileMatrix/attribution.json](./src/routes/attribution.ts) +- GET [/v1/attribution/:tileSet/:tileMatrix/summary.json](./src/routes/attribution.ts) + +### WMTS Capabilities APIs + +Get WMTS xml from the server to support QGIS and Arcgis + +- GET [/v1/tiles/:tileSet/:tileMatrix/WMTSCapabilities.xml](./src/routes/tile.wmts.ts) +- GET [/v1/tiles/:tileSet/WMTSCapabilities.xml](./src/routes/tile.wmts.ts) +- GET [/v1/tiles/WMTSCapabilities.xml](./src/routes/tile.wmts.ts) + diff --git a/packages/landing/README.md b/packages/landing/README.md index f8f87eaeb..497020a91 100644 --- a/packages/landing/README.md +++ b/packages/landing/README.md @@ -2,7 +2,6 @@ The landing page for basemaps https://basemaps.linz.govt.nz - ## Development To start a local test server there are two options @@ -21,4 +20,3 @@ The simple local server is used to validate html/css/js changes in the landing p yarn bundle node serve.mjs ``` - diff --git a/packages/linzjs-geojson/README.md b/packages/linzjs-geojson/README.md index 6dc163de2..c3412dafc 100644 --- a/packages/linzjs-geojson/README.md +++ b/packages/linzjs-geojson/README.md @@ -1,11 +1,13 @@ -# GeoJSON computation +# @linzjs/geojson + +## GeoJSON computation Utility functions for working with GeoJSON multi polygons and bounding boxes. In particular for handling the anti-meridian. ## Usage - ### Wgs84 + ```javascript import { Wgs84 } from '@linzjs/geojson'; @@ -21,7 +23,7 @@ assert(deepEqual(Wgs84.union([175, -42, -178, -41], [-170, -43, -160, -42]), [17 ### MultiPolygon ```javascript -import { clipMultipolygon, multiPolygonToWgs84 } from '@linzjs/geojson'; +import { clipMultipolygon, multiPolygonToWgs84 } from '@linzjs/geojson'; import * as Proj from 'proj4'; // polygons clipped to bounding box; no degenerate edges diff --git a/packages/server/README.md b/packages/server/README.md index c1dac3685..de4accd6b 100644 --- a/packages/server/README.md +++ b/packages/server/README.md @@ -5,6 +5,7 @@ WMTS/XYZ Tile server command line interface. This wraps the [@basemaps/lambda-tiler](https://github.com/linz/basemaps/blob/master/packages/lambda-tiler/README.md) into a standalone http server using [fastify](https://www.fastify.io/). ## Usage + Basemaps server expects a folder tree full of configuration, with multiple tilesets and styles configuration files. ```bash @@ -13,7 +14,7 @@ basemaps-server --config path/to/config/ ### Usage docker -The server is also published as a docker container +The server is also published as a [docker container](https://github.com/linz/basemaps/pkgs/container/basemaps%2Fserver) ```bash docker run -it \ @@ -36,9 +37,9 @@ bmc bundle --config config/ --output config.bundle.json basemaps-server --config config.bundle.json ``` - ### Usage with LINZ imagery -Usage with basemaps config, you will need access to basemaps' imagery cache + +Usage with basemaps config, you will need access to basemaps' imagery cache please contact basemaps@linz.govt.nz if you need access. @@ -49,12 +50,10 @@ bmc bundle --config basemaps-config/config --output config.bundle.json basemaps-server --config config.bundle.json ``` - ### Direct TIFF access If you have a folder of tiffs the `@basemaps/server` can index the folder and create tiles from it - For example given a structure where there are two folders full of tiffs ``` @@ -64,7 +63,6 @@ For example given a structure where there are two folders full of tiffs running `basemaps-server /images/00_gebco_2021_305-75m/ /images/10_geographx_nz_texture_shade_2012_8-0m/` will create two tile sets one for each folder `gebco_2021...` and `geographx_nz_t...` and then also create a combined layer in the order the tiffs are found. - ## Developing When running the `@basemaps/server` in development mode, ensure `@basemaps/landing` page has been built and bundled diff --git a/packages/smoke/README.md b/packages/smoke/README.md index 6a4220610..e8afe11d6 100644 --- a/packages/smoke/README.md +++ b/packages/smoke/README.md @@ -8,4 +8,4 @@ to run BASEMAPS_HOST=https://dev.basemaps.linz.govt.nz node --test ``` -*Requires Node >= 18* \ No newline at end of file +_Requires Node >= 18_ diff --git a/packages/sprites/README.md b/packages/sprites/README.md index 564f05bc6..1762852bb 100644 --- a/packages/sprites/README.md +++ b/packages/sprites/README.md @@ -59,4 +59,4 @@ The following test sprites come from [openstreetmap-americana](https://github.co - ./static/sprites/openstreetmap_poi_bus.svg - ./static/sprites/openstreetmap_poi_plane.svg - ./static/sprites/openstreetmap_shield_ca_qc_a_2.svg -- ./static/sprites/openstreetmap_shield_kr_expressway_2.svg +- ./static/sprites/openstreetmap_shield_kr_expressway_2.svg \ No newline at end of file diff --git a/packages/tiler-sharp/README.md b/packages/tiler-sharp/README.md new file mode 100644 index 000000000..21e5db364 --- /dev/null +++ b/packages/tiler-sharp/README.md @@ -0,0 +1,12 @@ +# @basemaps/tiler-sharp + +Module contains the functions to support xyz tile server to generate tiles by using [sharp](https://github.com/lovell/sharp) and [libvips](https://github.com/libvips/libvips). + +```typescript +const res = await compose({ + layers, // all the tiles using to create the new one. + format: 'webp', + background: { r: 0, g: 0, b: 0, alpha: 0 }, + resizeKernel: { in: 'lanczos3', out: 'lanczos3' }, + }); +``` diff --git a/packages/tiler/README.md b/packages/tiler/README.md index 6ee9091cc..f36e0929a 100644 --- a/packages/tiler/README.md +++ b/packages/tiler/README.md @@ -7,15 +7,14 @@ See `@basemaps/tiler-sharp` for how to run the composition pipeline in NodeJs ## Usage ```typescript -import {Tiler} from '@basemaps/tiler' +import { Tiler } from '@basemaps/tiler'; const tiler = new Tiler(256 /* Tile size px */); -const tiffs = [tiffA,tiffB]; // @cogeotiff/core GeoTiff's +const tiffs = [tiffA, tiffB]; // @cogeotiff/core GeoTiff's const layers = await tiler.tile(tiffs, x, y, z); // Layers is now the positioning and scaling information for the tiffs -import {TilerMaker} from '@basemaps/tiler-sharp' +import { TilerMaker } from '@basemaps/tiler-sharp'; const maker = new TileMaker(256); -const data = await maker.compose(layers) -console.log(data.buffer) // PNG image of the resulting layers - +const data = await maker.compose(layers); +console.log(data.buffer); // PNG image of the resulting layers ```