camptocamp / inkmap

A library for generating high-quality, printable maps on the browser.

inkmap, a library for generating high resolution maps in the browser

Live demo here!

Introduction

inkmap is based on OpenLayers and will generate maps in PNG format based on a given JSON specification.

inkmap can handle long-running jobs (e.g. A0 format in 300 dpi) and provides an API for following a job progress. It uses a service worker in the background provided the user browser supports OffscreenCanvas, and falls back (almost) seamlessly to the main thread if not.

Please note that the first version of inkmap has been entirely funded and supported by the French Ministry of Ecology as part of their Descartes web mapping toolkit, hosted here: https://adullact.net/projects/descartes/

Usage

Basic

To include the library in your project:

$ npm install --save @camptocamp/inkmap

Then import the different methods from the inkmap package:

import { print, downloadBlob } from '@camptocamp/inkmap';

print({
  layers: [ ... ],
  projection: 'EPSG:4326',
  ...
}).then(downloadBlob);

Advanced

inkmap offers advanced job monitoring through the use of Observables provided by the rxjs library.

Observables are different from Promises in that they can emit multiple values instead of just one, and are a very good fit for progress reporting.

To use an Observable, simply call its subscribe() method with a function as argument. The function will be called anytime a new value is emitted, like so:

import { getJobStatus } from '@camptocamp/inkmap';

...

getJobStatus(jobId).subscribe((jobStatus) => {
  // do something with the status
});

Note that for long-lived Observables (i.e. Observables that never completes) it is important to call unsubscribe() when the emitted values are not needed anymore. Open subscriptions to Observables might create memory leaks.

Enabling the service worker

inkmap can and will use a dedicated service worker for running print jobs if given the chance. This offers the following advantages:

• Jobs run in a separate thread, meaning the user navigation will not be impacted at all by any CPU-intensive task
• The service worker isn't tied to a window or tab, so jobs will continue running when the tab is closed (and even when the browser is closed, depending on the platform)
• Push notifications might be sent to the user when a print job complete (not implemented yet)

To enable this, the inkmap-worker.js file located in the dist folder must be published on the same path as the application using inkmap.

The worker file can be published either using a symbolic link or by actually copying the file, for example in the application build pipeline.

If using Webpack to build the application, a solution is to use the CopyWebpackPlugin:

module.exports = {
  ...
  plugins: [
     new CopyWebpackPlugin([
       {
         from: 'node_modules/@camptocamp/inkmap/dist/inkmap-worker.js',
         to: 'dist'
       },
     ]),
  ],
  ...
}

API

Important note: all API functions are named exports from the inkmap package.

print(jsonSpec: PrintSpec): Promise<Blob>

Takes in a PrintSpec object and returns a Promise which resolves to a Blob containing the final image.

queuePrint(jsonSpec: PrintSpec): Promise<number>

Takes in a PrintSpec object and returns a Promise which resolves to a job id (number) immediately.

getJobStatus(id: number): Observable<PrintStatus>

Takes in a job id and returns an Observable which will regularly emit PrintStatus objects, and complete when the final image was generated.

cancelJob(id: number): void

Takes in a job id, cancel the job and cease all requests immediately.

getJobsStatus(): Observable<PrintStatus[]>

Returns a long-running observable which emits an array of print job status. Once a job is finished it will appear once in the array and then will not be part of subsequent emissions.

Note: This observable will never complete. Don't forget to unsubscribe!

registerProjection(definition: ProjectionDefinition): void

Takes in a projection definition and registers it with proj4.

getAttributionsText(spec: PrintSpec): string

Returns the full attributions text of the spec.

getNorthArrow(spec: PrintSpec, sizeHint?: [number, string]): PrintableImage

Returns a PrintableImage containing the north arrow for the given spec. The image will be square and have the same DPI as the spec. A sizeHint (e.g. [3, 'cm']) can be provided to request a larger or smaller arrow. Supported size units are the same as in the PrintSpec type.

getScaleBar(spec: PrintSpec, minimumWidth?: [number, string]): PrintableImage

Returns a PrintableImage containing the scale bar for the given spec. The image will have the same DPI as the spec. A minimumWidth (e.g. [80, 'mm']) can be provided to request a smaller or larger scale bar. Supported size units are the same as in the PrintSpec type.

Note that for this scale bar to be relevant in a printed document, its real-world size has to be respected.

createLegend(jsonSpec: PrintSpec): Promise<Blob>

Takes in a PrintSpec object and returns a Promise which resolves to a Blob containing the final legend image.

PrintSpec type

A PrintSpec object describes the content and aspect of the map to be printed.

field	type	description
layers	Layer[]	Array of Layer objects that will be rendered in the map; last layers will be rendered on top of first layers.
size	[number, number] or [number, number, string]	Width and height in pixels, or in the specified unit in 3rd place; valid units are px, mm, cm, m and in.
center	[number, number]	Longitude and latitude of the map center.
dpi	number	Dot-per-inch, usually 96 for a computer screen and 300 for a detailed print.
scale	number	Scale denominator.
scaleBar	boolean | ScaleBarSpec	Indicates whether scalebar should be printed (true). Also allows to pass options object: {"position": "bottom-left", "units": "metric" } (default values). Possible values are: position: "bottom-left" | "bottom-right" units: "degrees" | "imperial" | "metric" | "nautical" | "us" (same as ol.control.ScaleLine)
northArrow	boolean | string	North arrow position; either 'top-left', 'bottom-left', 'bottom-right' or 'top-right'; true defaults to 'top-right'; absent or false means not to print the north arrow.
projection	string	Projection name. If starting with EPSG:, and other than EPSG:3857 or EPSG:4326, definition will be downloaded on [https://epsg.io/].
projectionDefinitions	[projectionDefinition]	Optional. Registers new projections from the definitions.
attributions	boolean | string	Position of the attributions to be printed on the map; either 'top-left', 'bottom-left', 'bottom-right' or 'top-right'; if not defined, attributions will not be printed.

Layer type

A Layer object describes a layer in the printed map.

field	type	description
type	string	Either XYZ, WMTS, WMS, WFS or GeoJSON.
url	string	URL or URL template for the layer; for XYZ layers, a URL can contain the following tokens: {a-d} for randomly choosing a letter, {x}, {y} and {z}.
opacity	number	Opacity, from 0 (hidden) to 1 (visible).
attribution	string	Attribution for the data present in the layer.
legend	boolean	Include this layer in the map legend. Defaults is false.

WMS layer type

Additional options for WMS layer type.

field	type	description
layer	string	Layer name.
version	string	Version of WMS protocol used: 1.1.1 or 1.3.0 (default).
tiled	boolean	Indicates whether the WMS layer should be requested as tiles. Defaults to false.
customParams	Object	Additional params used in all GetMap requests (optional).

WMTS layer type

Additional options for WMTS layer to define the layer source. See https://openlayers.org/en/latest/apidoc/module-ol_source_WMTS-WMTS.html for the full list of options. The following table introduces the common options to use.

field	type	description
requestEncoding	string	Request encoding: KVP, REST.
format	string	Image format. Only used when requestEncoding is 'KVP'. eg image/png.
layer	string	Layer name as advertised in the WMTS capabilities.
style	number	Style name as advertised in the WMTS capabilities.
projection	string	Projection.
matrixSet	string	Matrix set.
tileGrid	TileGrid	TileGrid object, see https://openlayers.org/en/latest/apidoc/module-ol_tilegrid_TileGrid-TileGrid.html for options

WFS layer type

Additional options for WFS layer type.

field	type	description
layer	string	Layer name.
version	string	Version of WFS protocol used: 1.0.0, 1.1.0 (default) or 2.0.0.
format	string	Format used when querying WFS, gml (default) or geojson. inkmap determines the GML parser based on the WFS version used.
style	object	JSON object in geostyler notation, defining the layer style.

GeoJSON layer type

Additional options for GeoJSON layer type.

field	type	description
geojson	object	Feature collection in GeoJSON format; coordinates are expected to be in the print job reference system.
style	object	JSON object in geostyler notation, defining the layer style.

projectionDefinition type

A projectionDefinition object describes a projection to be registered in proj4.

field	type	description
name	string	Name of the projection, written as prefix:code.
bbox	[number, number, number, number]	Extent of the projection, written as [maxlat, minlon, minlat, maxlon].
proj4	string	Proj4 definition string.

PrintStatus type

A PrintStatus object describes the status of a print job.

field	type	description
id	number	Job id.
progress	number	Job progress, from 0 to 1.
status	string	Either 'pending', 'ongoing', 'finished' or 'canceled'.
imageBlob	`Blob	null`
spec	PrintSpec	The spec used for this job.
sourceLoadErrors	SourceLoadError[]	Array of SourceLoadError objects.

SourceLoadError type

A SourceLoadError object contains the URL for tile sources which produced errors while loading data.

field	type	description
url	string	URL of the ol.source that encountered at least one 'tileloaderror' or 'imageloaderror'.

PrintableImage class

A PrintableImage is essentially a wrapper around a native image or canvas, with added information about its real world size.

method	return type	description
getImage()	HTMLImageElement or HTMLCanvasElement	Returns the native image to be drawn or printed.
getRealWorldDimensions(units: string)	[number, number]	Returns the real world dimensions of the image for a given unit (e.g. mm).
getDpi()	number	Returns the image DPI.

Architecture

Under the hood, inkmap will attempt to install a service worker on the page it is called. The service worker will then be in charge of loading all the map images and data, composing them together and giving them back to the application code.

Contributing

See CONTRIBUTING.

License

CeCILL-C

inkmap's Issues

Allow producing scale bar and north arrow as separate images

Currently the scale bar and north arrow are blended in the printed map.

Allowing to receive them as separate images would make printing PDF compositions easier, i.e. by putting these elements outside of the map, while still being assured that the scale bar is correct.

This would require also giving the size of the separate images in real world units if possible. Otherwise it would be tricky to include the scale bar as a separate element in the PDF.

Another option is to add getScaleBar and getNorthArrow APIs which could generate the images from a spec, without waiting for the whole map to be generated.

When printing multiple tiled WMS, the progress is not always going forward

Test with:

    {
      "layers": [
        {
          "type": "WMS",
          "url": "https://ows.mundialis.de/services/service",
          "layer": "OSM-WMS",
          "opacity": 1,
          "tiled": true
        },
        {
          "type": "WMS",
          "url": "https://ows.mundialis.de/services/service",
          "layer": "OSM-WMS",
          "opacity": 1,
          "tiled": true
        },
        {
          "type": "WMS",
          "url": "https://ows.mundialis.de/services/service",
          "layer": "OSM-WMS",
          "opacity": 0.85,
          "tiled": true
        },
        {
          "type": "WMS",
          "url": "https://ows.mundialis.de/services/service",
          "layer": "OSM-WMS",
          "opacity": 0.95,
          "tiled": true
        }
      ],
      "size": [
        53.42439024390244,
        46.92682926829268,
        "mm"
      ],
      "center": [
        1.8168988068369898,
        47.5727467646945
      ],
      "dpi": 300,
      "scale": 387837.8378378379,
      "projection": "EPSG:3857",
      "scaleBar": true,
      "northArrow": true
    }

Add a mechanism for validating a given spec

This would make for a better developer experience by explaining precisely if/what something is wrong in a spec.

Also it would mean all the code handling the spec can assume that it is 100% correct.

Allow specifying a BBOX instead of a center + scale

Specifying a bbox should be enough to print a map when associated with size and dpi. This would be an alternative (and simpler) way of specifying a viewport.

Send the DPI value to GetMap requests

Geoserver supports a format_options=dpi:... parameter in WMS getmap requests: https://docs.geoserver.org/latest/en/user/services/wms/vendor.html

Mapserver supports map_resolution=..., see https://mapserver.org/cgi/controls.html#using-mapserver-version-5

QGIS supports DPI=..., see https://docs.qgis.org/2.18/en/docs/user_manual/working_with_ogc/server/services.html#id2

I guess inkmap could send all three formats in the request, hopefully that won't cause any errors (doubt it)

This is really valuable since this would mean having high DPI prints with readable text/symbols when using WMS

Multiple calls to `queuePrint` result in same job id

I have a dynamic number of map selections, which I queue for printing:

  // queuePrint gives the same id for all invocations
  const printJobIds = await Promise.all(
    selectionGeometries.map((polygon) =>
      queuePrint(createPrintSpec(polygon, [layer], size))
    )
  );
  const statusObservables: Observable<PrintStatus>[] = printJobIds.map((id) =>
    getJobStatus(id)
  );
  merge(...statusObservables)
    .pipe(finalize(() => pdf.download("map.pdf")))
    .subscribe((jobStatus) => {
      reportProgress(jobStatus);
      if (jobStatus.status === "finished" && jobStatus.imageBlob !== null) {
        pdf.addImageBlob(jobStatus.imageBlob);
      }
    });

The printJobIds returned are all the same, the id of the first job. Hence all statusObservables observe the same job.
Looking at the "[inkmap] message to main:" console logs, all the jobs are properly queued and are processed, only the returned ids are incorrect from queuePrint.

The reason for this seems to be that calls to queuePrint all subscribe to the next value emitted from newJob$. It's a multicast observable and all the observers will take the first value it emits. Which is the id of the first job that the worker reports to main.

export function queuePrint(printSpec) {
  messageToPrinter(MESSAGE_JOB_REQUEST, { spec: printSpec });
  return newJob$
    .pipe(
      take(1),
      map((job) => job.id)
    )
    .toPromise();
}

The asynchronicity of this makes it a bit complicated, I guess the easiest option to solve this would be to manage the job ids in the main thread and report the new id eagerly back to the caller. The message to the worker would then include the spec and the job id, which the worker will use for reporting back. Perhaps the id should be a UUID to avoid keeping state for the counter in this case.

DPI is not handled correctly

DPI should change the accuracy of the print, not the extent.

Same spec with

50 dpi

300 dpi

Support for API authentication

Some tile sources, like the Maanmittauslaitos WMTS api (page in Finnish only) in Finland, require API authentication to fetch tile data.

In my use case I was able pass the api key as part of the tile url as an url parameter. However it would be more robust to be able to add it as a header for the http requests.

I propose two mechanisms to support api authentication. These could be optional configuration in the printSpec.

• ability to add query params as key/value pairs
• custom headers that will be used for the tile requests

Incorrect documentation for PrintStatus

The documentation states the following:

PrintStatus type

A PrintStatus object describes the status of a print job.

field	type	description
id	number	Job id.
progress	number	Job progress, from 0 to 1.
status	string	Either 'pending', 'ongoing', 'finished' or 'canceled'.
resultImageUrl	string	An URL used to access the print result (PNG image). This will only be available once the job status is 'finished'.

The actual PrintStatus emitted by the observable returned from getJobStatus([id]) looks like the following. imageBlob is null until the operation is finished.

{
  id: 0
  ​imageBlob: Blob { size: 4012847, type: "image/png" }
  ​progress: 1
  ​sourceLoadErrors: Array []
  ​spec: Object { dpi: 300, scale: 3260.5795017802066, projection: "EPSG:3067", … }
  ​status: "finished"
}

Adapt the size of the north arrow and scale bar

At high DPI the scale bar and north arrow are almost invisible as they are much to small.

The `print` method sometimes fail to return a Blob when print area is outside of layer bbox

See jahow/hiking-trails-print#1

WFS layers fail when using service worker

GML geometries are parsed using the OpenLayers format utils, which rely on DOMParser. This API is not available in workers.

A workaround could be to use https://github.com/xmldom/xmldom which apparently provides an identical API as DOMParser but compatible with a worker environment.

Pass inline geojson to print specification

Allow the user to pass geometries to the print job specification.

Can't resolve 'd3-selection' in '...\node_modules\geostyler-legend\dist\LegendRenderer'

C:\Users\user\Downloads\inkmap>npm run demo

@camptocamp/[email protected] demo C:\Users\user\Downloads\inkmap
webpack-dev-server --config demo/webpack.config.js

i ｢wds｣: Project is running at http://localhost:8081/
i ｢wds｣: webpack output is served from /
i ｢wds｣: Content not from webpack is served from C:\Users\user\Downloads\inkmap\demo
× ｢wdm｣: Hash: db444d23ff938e1a70ae
Version: webpack 4.46.0
Time: 9951ms
Built at: 24/08/2022 16:45:14
Asset Size Chunks Chunk Names
0.js 814 KiB 0 [emitted]
0.js.map 687 KiB 0 [emitted] [dev]
1.js 46 KiB 1 [emitted]
1.js.map 53.1 KiB 1 [emitted] [dev]
2.js 375 KiB 2 [emitted]
2.js.map 428 KiB 2 [emitted] [dev]
app.js 4.68 MiB app [emitted] app
app.js.map 4.76 MiB app [emitted] [dev] app
index.html 25.5 KiB [emitted]
inkmap-worker.js 3.95 MiB inkmap-worker [emitted] inkmap-worker
inkmap-worker.js.map 3.89 MiB inkmap-worker [emitted] [dev] inkmap-worker
Entrypoint app = app.js app.js.map
Entrypoint inkmap-worker = inkmap-worker.js inkmap-worker.js.map
[0] multi (webpack)-dev-server/client?http://localhost:8081 ./demo/index.js 40 bytes {app} [built]
[1] multi (webpack)-dev-server/client?http://localhost:8081 ./src/worker/index.js 40 bytes {inkmap-worker} [built]
[./demo/elements/custom-button.js] 1.4 KiB {app} [built]
[./demo/elements/custom-progress.js] 3.3 KiB {app} [built]
[./demo/elements/print-spec.js] 4.52 KiB {app} [built]
[./demo/elements/progress-bars.js] 728 bytes {app} [built]
[./demo/examples/01-simple.js] 603 bytes {app} [built]
[./demo/examples/02-progress.js] 1 KiB {app} [built]
[./demo/examples/03-cancel.js] 1.3 KiB {app} [built]
[./demo/examples/04-jobs.js] 1010 bytes {app} [built]
[./demo/examples/05-pdf.js] 2.27 KiB {app} [built]
[./demo/examples/06-projection.js] 897 bytes {app} [built]
[./demo/index.js] 419 bytes {app} [built]
[./node_modules/webpack-dev-server/client/index.js?http://localhost:8081] (webpack)-dev-server/client?http://localhost:8081 4.29 KiB {app} {inkmap-worker} [built]
[./src/worker/index.js] 302 bytes {inkmap-worker} [built]
+ 1196 hidden modules

ERROR in ./node_modules/geostyler-legend/dist/LegendRenderer/LegendRenderer.js
Module not found: Error: Can't resolve 'd3-selection' in 'C:\Users\user\Downloads\inkmap\node_modules\geostyler-legend\dist\LegendRenderer'
@ ./node_modules/geostyler-legend/dist/LegendRenderer/LegendRenderer.js 42:21-44
@ ./src/shared/widgets/legends.js
@ ./src/main/index.js
@ ./demo/examples/01-simple.js
@ ./demo/index.js
Child HtmlWebpackCompiler:
1 asset
Entrypoint HtmlWebpackPlugin_0 = __child-HtmlWebpackPlugin_0
[./node_modules/html-webpack-plugin/lib/loader.js!./demo/index.html] 15.8 KiB {HtmlWebpackPlugin_0} [built]
i ｢wdm｣: Failed to compile.
Error from chokidar (C:): Error: EBUSY: resource busy or locked, lstat 'C:\DumpStack.log.tmp'

npm WARN [email protected] requires a peer of d3@^6.7.0 but none is installed. You must install peer dependencies yourself.

Support TMS Vector Tiles

Hello!
Reading the api and the source code, it seems that TMS Vector Tiles are not supported by InkMap.
Is that a correct analysis? Is there any work planned for this feature?
Thanks in advance for you answer.

boostrapcdn.com not reliable

Hi,
I'm developing with the demo and I sometimes have https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js or/and https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css which can't be loaded.
Should those files be present in source code to avoid this behavior?