versatiles-svg-renderer
    Preparing search index...

    Interface RenderToPNGOptions

    Options for renderToPNG: everything RenderToSVGOptions takes, plus the pixel density of the image and the fonts to draw labels with.

    interface RenderToPNGOptions {
        bearing?: number;
        fetch?: FetchFunction;
        fonts?: Record<string, string | readonly string[]>;
        globalState?: GlobalState;
        height?: number;
        images?: readonly StyleImage[];
        labels?: LabelMode;
        lat?: number;
        lon?: number;
        onWarning?: (message: string) => void;
        padding?: number | Padding;
        renderLabels?: boolean;
        scale?: number;
        style: StyleSpecification;
        width?: number;
        zoom?: number;
    }

    Hierarchy (View Summary)

    Index
    bearing?: number

    The compass direction that is up, in degrees, as in MapLibre: 90 puts east at the top. The map turns around the image's center; labels stay upright.

    the style's bearing, else 0

    Loads tiles, sprites, TileJSON documents and GeoJSON data, like fetch, which is the default. Pass your own to send headers, go through a proxy, or keep tiles in a cache on disk.

    It is called with the URL only, except to read part of a file, a PMTiles archive: then also with { headers: { Range: 'bytes=…' } }, which it should pass on.

    It must return a real Response, and its status matters: a 404 or 204 means the server has no such tile, which is remembered (see SVGMapRendererOptions.tileCacheSize); any other error status, or a rejected promise, counts as failed, and the next render tries again.

    the global fetch

    fonts?: Record<string, string | readonly string[]>

    Font files to draw labels with, as { "<text-font name>": "<path to a font file>" }, or with a list of files for a name.

    A style only names its fonts ("text-font": ["noto_sans_regular"]). MapLibre draws them from pre-rendered glyphs on the style's glyph server, which this renderer does not use: it draws text with real font files instead. Map each name the style uses to a TTF, OTF, WOFF or WOFF2 file. A name left unmapped falls back to a font installed on the machine, which is usually not the one the style asked for.

    A glyph server covers many scripts under one name, while a font file often covers only some of them (as web fonts split into subsets do). Give such a name all of its files: a character missing from one is drawn from the next that has it, before any font installed on the machine.

    Fonts are registered process-wide, so a name registered by one call stays available to every later call. Matters when RenderToSVGOptions.labels is 'text', and for labels in scripts whose letters combine (Indic scripts, Thai, …), which are drawn as text in every mode.

    globalState?: GlobalState

    Values for the style's global state, read by global-state expressions, e.g. to switch the language or a theme of a style. They override the defaults in the style's state, like map.setGlobalStateProperty(name, value) in MapLibre GL JS.

    the defaults of the style's state

    height?: number

    Height of the image in pixels.

    1024

    images?: readonly StyleImage[]

    Images that the style uses besides those of its sprite, like map.addImage(id, image, { pixelRatio, sdf }) in MapLibre GL JS: for icon-image, fill-pattern, line-pattern and background-pattern, by their id, which no sprite id is put before. An SDF image is colored by icon-color and its halo, like one of the sprite.

    As in MapLibre GL JS, where addImage fails for an id that exists, an image of the sprite with the same id is drawn instead, reported through SVGMapRendererOptions.onWarning. In an SVG, each image is a data URI of a PNG file without compression.

    none
    
    labels?: LabelMode

    Whether and how to draw the style's symbol layers, its labels and icons:

    • 'none': neither labels nor icons.
    • 'text': labels as <text> naming the style's fonts (text-font), which whatever displays the SVG resolves, so they show in the intended typeface only where that font is installed. In PNG output, with the fonts given by fonts.
    • 'glyphs': labels as the style's own glyphs (glyphs), the letter shapes MapLibre draws, traced into outlines: exact in every viewer and editor, but not text. Each glyph is defined once and reused.
    • 'glyphs-text': as 'glyphs', with the text laid invisibly over the outlines, so labels stay selectable and searchable. (In PNG output, the same as 'glyphs'.)

    Labels are placed as in MapLibre: at points, inside each polygon at the point farthest from its edges, and along lines; labels and icons that would overlap one placed before are left out, from the top layer down. With glyphs, they are laid out with MapLibre's own metrics; as text, with the widths of Noto Sans. A style without glyphs, or glyphs that cannot be loaded, fall back to 'text', reported through onWarning. Labels in scripts whose letters combine (Indic scripts, Thai, Khmer, …) or with letters that carry marks are drawn as text in every mode, as MapLibre draws them with the browser's fonts.

    'none', or as given by SVGMapRendererOptions.renderLabels

    lat?: number

    Latitude of the map centre, in degrees.

    the latitude of the style's center, else 0

    lon?: number

    Longitude of the map centre, in degrees.

    the longitude of the style's center, else 0

    onWarning?: (message: string) => void

    Called with a message for each part of the style the renderer does not draw: a layer type, a layer property, a source, or a TileJSON document that could not be loaded. Each message is reported once per instance. Pass () => {} to silence them.

    Properties that make no difference to a flat, north-up map (e.g. *-pitch-alignment) are not reported, nor are symbol layers unless SVGMapRendererOptions.labels is set.

    console.warn

    padding?: number | Padding

    Space around the map's center, in pixels, as MapLibre's padding: the center (lon, lat) sits in the middle of the area inside it, e.g. to keep it clear of a panel laid over the image. A number applies to all sides.

    0

    renderLabels?: boolean

    Draw the style's labels and icons.

    Use SVGMapRendererOptions.labels: true is 'glyphs-text', false is 'none'.

    false

    scale?: number

    Pixel density, like a device pixel ratio. The image is width * scale by height * scale pixels, while the map is laid out as if it were width by height — so lines, text and icons keep their size and gain detail, as in a 2× screenshot. Use 2 for a sharp image on high-resolution screens.

    1

    style: StyleSpecification

    The MapLibre style to render.

    A source may list its tile URLs (tiles: [...]) or point at a TileJSON document (url: '.../tiles.json'), which is fetched once, like the sprite, with SVGMapRendererOptions.fetch. As in MapLibre GL JS, tiles, minzoom, maxzoom and the like come from the document unless the style sets them, and relative tile URLs are resolved against the document's URL. A PMTiles archive (url: 'pmtiles://https://.../tiles.pmtiles') is read as with the pmtiles protocol in MapLibre GL JS, which needs no setup here. A GeoJSON source's data may be a URL too. A source whose TileJSON or GeoJSON cannot be loaded is left out, and the next render tries again.

    width?: number

    Width of the image in pixels.

    1024

    zoom?: number

    Zoom level, as in MapLibre: each step doubles the scale. Fractional values are allowed.

    the style's zoom, else 2