Render static map images
npm install @tinkatinka/static-mapTo generate the final image node-canvas is being used.
bash
$ npm install @tinkatinka/static-map
`Usage
ts
import { StaticMap } from '@tinkatinka/static-map';
const map = new StaticMap(...);
`
The constructor can be called with an optional object, overriding the defaults:`ts
{
width: number; // width of the image in pixels [default: 512]
height: number; // height of the image in pixels [default: 512]
padding: number; // padding in pixels [default: 0]
paddingX?: number; // horizontal padding (overrides padding)
paddingY?: number; // vertical padding (overrides paddings)
paddingLeft?: number; // left padding (overrides paddingX)
paddingRight?: number; // right padding (overrides paddingX)
paddingTop?: number; // top padding (overrides paddingY)
paddingBottom?: number; // bottom padding (overrides paddingY)
extent?: LatLngBounds; // extent of the map [default: undefined]
scaling: boolean; // scale image to match size and padding exactly [default: true]
tileURL: string; // template string for tile URL [default: 'https://tile.openstreetmap.org/{z}/{x}/{y}.png']
tileSize: number; // size of tiles [default: 256]
tileMaxZoom: number; // maximum zoom available for tiles [default: 20]
tileCache?: string; // path to a cache directory for tiles [default: undefined]
backgroundColor?: string; // image background color (CSS string) [default: undefined]
grayscale: boolean; // apply a grayscale filter to map tiles (not overlays) [default: false]
}
`
Note: Either an explicit of the map or at least one overlay (see below) must be defined,
otherwise the image generation will fail.$3
#### LatLng
`ts
{
lat: number; // latitude
lng: number; // longitude
}
`#### LatLngBounds
ts
{
min: LatLng; // minimum point
max: LatLng; // maximum point
}
`$3
#### Lines
ts
.addLine(src: LatLng, dst: LatLng, options?: Partial);.addLines(points: LatLng[], options?: Partial);
`Options:
ts
interface StaticMapLineOptions {
strokeStyle: string; // css stroke style [default: 'black']
lineWidth: number; // line width in pixels [default: 1.0]
lineCap: 'butt' | 'round' | 'square'; // [default: 'round']
lineJoin: 'bevel' | 'round' | 'miter'; // [default: 'round']
}
`#### Circles
ts
.addCircle(center: LatLng, options?: Partial);
`Options:
ts
interface StaticMapCircleOptions {
radius: number; // in pixels [default: 5.0]
strokeStyle?: string; // css stroke style or undefined for no stroke [default: 'black']
lineWidth: number; // line width in pixels [default: 1.0]
fillStyle?: string; // css fill style or undefined for no fill [default: 'rgba(0, 0, 0, 0.3)']
}
`#### Rectangles
ts
.addRectangle(bounds; LatLngBounds, options?: Parital);
`Options:
ts
interface StaticMapRectOptions {
strokeStyle: string; // css stroke style [default: 'black']
lineWidth: number; // line width in pixels [default: 1.0]
lineCap: 'butt' | 'round' | 'square'; // [default: 'round']
lineJoin: 'bevel' | 'round' | 'miter'; // [default: 'round']
}
`#### Polygons
ts
addPolygon(points: LatLng[], options?: Partial);
`Options:
ts
interface StaticMapPolygonOptions {
strokeStyle: string; // css stroke style [default: 'black']
lineWidth: number; // line width in pixels [default: 1.0]
lineCap: 'butt' | 'round' | 'square'; // [default: 'round']
lineJoin: 'bevel' | 'round' | 'miter'; // [default: 'round']
}
`#### Text
ts
.addText(text: string, anchor: LatLng, options?: Partial);
`Options:
ts
interface StaticMapTextOptions {
px: number; // padding x [default: 0]
py: number; // padding y [default: 0]
maxWidth?: number; // text max width [default: undefined]
direction: string; // default: 'ltr'
font: string; // default: '12px sans-serif'
textAlign: string; // default: 'center'
textBaseline: string; // default: 'middle'
strokeStyle?: string; // css stroke style or undefined for no stroke [default: undefined]
lineWidth: number; // line width in pixels [default: 1.0]
fillStyle?: string; // css fill style or undefined for no fill [default: 'black']
}
`#### Images
ts
.addImage(src: string, bounds: LatLngBounds);
`#### Scales
ts
.addScale(options?: PartialDeep);
`Options:
ts
export interface StaticMapScaleOptions {
units: 'metric' | 'imperial'; // [default: 'metric']
position: '(bottom|top)(left|right)'; // [default: 'bottomleft']
height: number; // in pixels [default: 16]
maxWidth: number; // percent [default: 20]
mx: number; // margin x in percent [default: 4]
my: number; // margin y in percent [default: 4]
boxStyle: { // drawing style of the box
lineWidth: number; // line width in pixels [default: 1.0]
lineCap: 'butt' | 'round' | 'square'; // [default: 'square']
lineJoin: 'bevel' | 'round' | 'miter'; // [default: 'miter']
strokeStyle: string; // css stroke style [default: 'black']
fillStyle: string; // css fill style [default: 'rgba(255, 255, 255, 0.3)']
};
textStyle: { // drawing style of the label
font: string; // [default: '12px sans-serif']
lineWidth: number; // line width in pixels [default: 1.0]
lineCap: 'butt' | 'round' | 'square'; // [default: 'square']
lineJoin: 'bevel' | 'round' | 'miter'; // [default: 'miter']
strokeStyle: string; // css stroke style [default: 'black']
fillStyle: string; // css fill style [default: 'rgba(255, 255, 255, 0.3)']
};
}
`$3
Can be obtained via async functionsts
.renderToDataURL(): Promise.renderToBuffer(): Promise
.renderToCanvas(): Promise
`All of them will fail if the
of the map is not explicitly defined or cannot be computed (because there are
no overlays).Examples
$3
`ts
import { StaticMap } from '@tinkatinka/static-map';
const map = new StaticMap({
width: 512,
height: 512,
extent: {
min: { lat: 52.4, lng: 13.3 },
max: { lat: 52.6, lng: 13.5 }
}
});
const src = await map.renderToDataURL();
...
`$3
ts
import { StaticMap } from '@tinkatinka/static-map';
const map = new StaticMap({
width: 512,
height: 512,
paddingX: 32,
paddingY: 32,
tileCache: '/tmp/tiles'
})
.addImage('https://my.funky.src/image.png', {
min: { lat: 1.0, lng: 2.0 },
max: { lat: 2.0, lng: 3.0 }
});
const buffer = await map.renderToBuffer();
...
`$3
ts
import { StaticMap } from '@tinkatinka/static-map'
const map = new StaticMap({
extent: {
min: { lat: 52.4, lng: 13.3 },
max: { lat: 52.6, lng: 13.5 }
},
grayscale: true,
tileCache: '/tmp/tiles'
});
const canvas = await map.renderToCanvas();
const ctx = canvas.getContext('2d');
ctx.textAlign = 'end';
ctx.textBaseline = 'bottom';
ctx.font = '16px sans-serif';
ctx.fillStyle = 'blue';
ctx.fillText('© OpenStreetMap contributors', canvas.width-8, canvas.height-8);
const buffer = await canvas.toBuffer();
...
``E.g. see OpenStreetMap for information regarding the copyright and
attribution of OpenStreetMap tiles.