gws.gis.render

Map rendering.

This package renders maps for printing, exporting and templates. It works with three kinds of objects, defined in types.pyinc:

  • gws.MapView: the geometry of a rendered map: bounds, center, scale, rotation, size in mm and pixels and the DPI.

  • gws.MapRenderInput: what to render: the map size, the bbox or the center and scale, the target CRS, the DPI and a list of input planes (image layers, SVG layers, features, images, SVG “soups”).

  • gws.MapRenderOutput: the rendered map, a list of output planes, each either a raster image or a list of SVG elements, and the view.

Design

render_map creates two views of the map: a vector view, always at gws.lib.uom.PDF_DPI, and a raster view. For pixel sizes, the raster view is the vector view. For mm sizes, rasters use the requested DPI, clamped to MIN_DPI and MAX_DPI.

Input planes are processed bottom-up. Image layers are rendered by the layer as a box, SVG layers and features are converted to SVG elements. Consecutive raster planes are composed into one image, consecutive SVG planes are merged into one element list, so the output alternates between raster and SVG planes. The background color is applied to the first raster plane only. A plane that fails to render is logged and skipped.

The output can be converted to HTML (output_to_html_element, output_to_html_string), where raster planes become img tags and SVG planes svg elements, stacked in a div.

The package also creates views from a center and scale or from a bbox (map_view_from_center, map_view_from_bbox).

Example:

mri = gws.MapRenderInput(
    bbox=(0, 0, 1000, 1000),
    targetCrs=gws.lib.crs.WEBMERCATOR,
    dpi=300,
    mapSize=(200, 200, gws.Uom.mm),
    planes=[
        gws.MapRenderInputPlane(type=gws.MapRenderInputPlaneType.imageLayer, layer=layer),
    ],
    user=user,
)
mro = gws.gis.render.render_map(mri)
html = gws.gis.render.output_to_html_string(mro)

Source code: gws.gis.render

Package Contents

gws.gis.render.map_view_from_bbox(size: gws.UomSize, bbox: gws.Extent, crs: gws.Crs, dpi: int, rotation: float = 0) → gws.MapView

Create a map view from a bounding box.

The scale is computed from the bbox width and the pixel width.

Parameters:

  • size – Map size in mm or pixels.

  • bbox – Bounding box.

  • crs – CRS of the view.

  • dpi – Resolution in dots per inch.

  • rotation – Rotation angle in degrees.

Returns:

A map view.

gws.gis.render.map_view_from_center(size: gws.UomSize, center: gws.Point, crs: gws.Crs, dpi: int, scale: float, rotation: float = 0) → gws.MapView

Create a map view from a center point and a scale.

The extent is computed from the size in mm, assuming that the CRS units are meters.

Parameters:

  • size – Map size in mm or pixels.

  • center – Center point.

  • crs – CRS of the view.

  • dpi – Resolution in dots per inch.

  • scale – Scale denominator.

  • rotation – Rotation angle in degrees.

Returns:

A map view.

gws.gis.render.MAX_DPI = 1200

Max. DPI for raster planes.

gws.gis.render.MIN_DPI

Min. DPI for raster planes.

gws.gis.render.output_to_html_element(mro: gws.MapRenderOutput, wrap='relative') → gws.XmlElement

Convert a render output to an HTML element.

Image planes are saved to ephemeral PNG files and become img tags, SVG planes become svg elements, all absolutely positioned in a div of the view’s mm size.

Parameters:

  • mro – Render output.

  • wrap – CSS position of the div: relative, absolute or fixed. With any other value, the div has no style.

Returns:

A div element.

gws.gis.render.output_to_html_string(mro: gws.MapRenderOutput, wrap='relative') → str

Convert a render output to an HTML string.

Parameters:

  • mro – Render output.

  • wrap – CSS position of the wrapper div, see output_to_html_element.

Returns:

The HTML of a div element.

gws.gis.render.render_map(mri: gws.MapRenderInput) → gws.MapRenderOutput

Render a map.

Planes are rendered bottom-up. Consecutive raster planes are composed into one image plane, consecutive vector planes into one SVG plane. Errors in a plane are logged and the plane is skipped. If mri.notify is set, it is called with begin_plane and end_plane for each plane.

Parameters:

mri – Render input.

Returns:

The render output, with the vector view as its view.

Raises:

gws.Error – If the map size unit is neither mm nor pixels.