Reference

renderer.__version__: str

The version.

Rendering

renderer.render.render(components: Pla2File, config: Config, save_dir: Path | None = None, processes: int = 2, tiles: list[TileCoord] | None = None, zooms: list[int] | None = None, offset: Vector = [0, 0], prepare_mp_config: MultiprocessConfig = MultiprocessConfig(batch_size=2, chunk_size=8, serial=False), part1_mp_config: MultiprocessConfig = MultiprocessConfig(batch_size=2, chunk_size=8, serial=False), part2_mp_config1: MultiprocessConfig = MultiprocessConfig(batch_size=2, chunk_size=8, serial=False), part2_mp_config2: MultiprocessConfig = MultiprocessConfig(batch_size=2, chunk_size=8, serial=False), part3_mp_config: MultiprocessConfig = MultiprocessConfig(batch_size=2, chunk_size=8, serial=False)) → dict[TileCoord, Image.Image]

Renders tiles from given coordinates and zoom values.

Parameters:

• components (Pla2File) – a JSON of components

• config – The configuration of the renderer

• save_dir – The directory to save tiles to, None to make it not save

• processes – The number of processes to run for rendering

• tiles – a list of tiles to render

• zooms – a list of zooms to render

• offset – the offset to shift all node coordinates by, given as (x,y)

• prepare_mp_config – The configuration for the data-dumping of the preparation stage

• part1_mp_config – The configuration for the processing of part 1

• part2_mp_config1 – The configuration for the 1st processing of part 2

• part2_mp_config2 – The configuration for the 2nd processing of part 2

• part3_mp_config – The configuration for the processing of part 3

renderer.render.prepare.prepare_render(components: Pla2File, config: Config, tiles: list[TileCoord] | None = None, zooms: list[int] | None = None, offset: Vector = [0, 0], prepare_mp_config: MultiprocessConfig = MultiprocessConfig(batch_size=2, chunk_size=8, serial=False)) → dict[TileCoord, list[list[Component]]]

The data-preparing step of the rendering job. Check render() for the full list of parameters

class renderer.render.part1.Part1Consts(zoom: ~renderer.misc_types.zoom_params.ZoomParams, export_id: str = 'unnamed', temp_dir: ~pathlib.Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/tile-renderer/checkouts/latest/docs/temp'), skin: ~renderer.skin_type.Skin = <renderer.skin_type.Skin object>, assets_dir: ~pathlib.Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/tile-renderer/checkouts/latest/renderer/skins/assets'), coord_to_comp: dict[WorldCoord, list[Component]] = <factory>)

The constants used for part 1

coord_to_comp: dict[WorldCoord, list[Component]]

A dictionary of world coordinates to the components that have nodes at said coordinate

renderer.render.part1.render_part1(config: Config, mp_config: MultiprocessConfig = MultiprocessConfig(batch_size=2, chunk_size=8, serial=False)) → None

Part 1 of the rendering job. Check render() for the full list of parameters

renderer.render.part2.render_part2(config: Config, mp_config1: MultiprocessConfig = MultiprocessConfig(batch_size=2, chunk_size=8, serial=False), mp_config2: MultiprocessConfig = MultiprocessConfig(batch_size=2, chunk_size=8, serial=False)) → dict[TileCoord, list[TextObject]]

Part 2 of the rendering job. Check render() for the full list of parameters

renderer.render.part3.render_part3(config: Config, save_dir: Path | None = None, mp_config: MultiprocessConfig = MultiprocessConfig(batch_size=2, chunk_size=8, serial=False)) → dict[TileCoord, Image.Image]

Part 3 of the rendering job. Check render() for the full list of parameters

class renderer.render.text_object.TextObject(img: Image.Image, center: ImageCoord, width_height: tuple[float, float], rot: float, zoom: int, config: Config)

A text to be pasted into the map at part 3

bounds: list[Polygon]

The bounds of the text in each image

center: list[WorldCoord]

The centers of each image

export_id: str = 'unnamed'

The export ID of the render job

classmethod from_multiple(*text_object: TextObject) → TextObject

Create a new compound TextObject from multiple TextObjects

image: list[UUID]

A list of UUIDs, each representing an image in the temporary folder

static img_to_uuid(img: Image.Image, config: Config) → UUID

Puts the image into the temporary directory and returns the UUID corresponding to the image

static remove_img(u: UUID, config: Config) → None

Remove the image from the temporary directory

Raises:

FileNotFoundError – If the UUID is invalid

temp_dir: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/tile-renderer/checkouts/latest/docs/temp')

The temporary directory that the images belong to

to_tiles(zoom: ZoomParams) → list[TileCoord]

Find the tiles that the text will be rendered in

static uuid_to_img(u: UUID, config: Config) → Image.Image

Retrieves an image object, given its corresponding UUID

Raises:

FileNotFoundError – if the UUID is invalid

class renderer.render.multiprocess.MultiprocessConfig(batch_size: int = 2, chunk_size: int = 8, serial: bool = False)

The configuration for each multiprocessing job

batch_size: int = 2

How many processes to run at once running the task

chunk_size: int = 8

The number of tasks to do at one spawn

serial: bool = False

Whether to run the tasks serially instead

renderer.render.multiprocess.multiprocess(iterated: list[_I], const_data: _D, f: Callable[[ObjectRef[ProgressHandler[_I]] | None, _I, _D], _R | None], msg: str, num_operations: int | None = None, mp_config: MultiprocessConfig = MultiprocessConfig(batch_size=2, chunk_size=8, serial=False)) → list[_R]

Multiprocess a task

Parameters:

• iterated – The objects to iter over for each task

• const_data – The object that will be the same on all tasks

• f – The function to be run with the multiprocessor, that takes in an (optional) ProgressHandler, an item of iterated and const_data and returns a result

• msg – The message to show for the progress bar

• num_operations – The number of operations (or the total number of ProgressHandler.add() calls during the multiprocess job)

• mp_config – The configuration for the multiprocess job

renderer.render.utils.part_dir(config: Config, part: int) → Path

Retrieve the directory for data from each of the parts

renderer.render.utils.text_object_path(config: Config, id_: UUID) → Path

Retrieve the directory for a text object

renderer.render.utils.wip_tiles_dir(config: Config) → Path

Retrieve the directory for half-complete tiles

Types

class renderer.misc_types.Pla1ComponentJson

Represents a component JSON object.

renderer.misc_types.Pla1ComponentListJson

Represents a component list JSON.

class renderer.misc_types.Pla1NodeJson

Represents a node JSON object.

renderer.misc_types.Pla1NodeListJson

Represents a node list JSON.

class renderer.misc_types.SkinInfo

Represents the info portion of a skin JSON.

class renderer.misc_types.SkinJson

Represents a skin JSON.

class renderer.misc_types.SkinType

Represents a component type in the types portion of a skin JSON.

class renderer.misc_types.config.Config(zoom: ~renderer.misc_types.zoom_params.ZoomParams, export_id: str = 'unnamed', temp_dir: ~pathlib.Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/tile-renderer/checkouts/latest/docs/temp'), skin: ~renderer.skin_type.Skin = <renderer.skin_type.Skin object>, assets_dir: ~pathlib.Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/tile-renderer/checkouts/latest/renderer/skins/assets'))

The configuration for the render job.

assets_dir: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/tile-renderer/checkouts/latest/renderer/skins/assets')

The asset directory for the skin

export_id: str = 'unnamed'

The skin to use for rendering the tiles

skin: Skin = <renderer.skin_type.Skin object>

The skin to use for rendering the tiles

temp_dir: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/tile-renderer/checkouts/latest/docs/temp')

The temporary data folder that will be used to save data

zoom: ZoomParams

A ZoomParams object

class renderer.misc_types.coord.Bounds(x_max: _T, x_min: _T, y_max: _T, y_min: _T)

Represents a bounding box, like a rectangle

class renderer.misc_types.coord.Coord(_x: float, _y: float)

Represents a 2-dimensional point

static dec_hook(obj: tuple[float, float]) → Coord

Decoding hook for msgspec

static enc_hook(obj: Coord) → tuple[int, int]

Encoding hook for msgspec

property point: Point

Returns a Shapely point

class renderer.misc_types.coord.ImageCoord(_x: float, _y: float)

Represents a 2-dimensional coordinate on an image

to_world_coord(tile_coord: TileCoord, config: Config) → WorldCoord

Converts the coordinate to a WorldCoord

Parameters:

• tile_coord – The tile coordinate that the coordinate is part of

• config – The configuration

class renderer.misc_types.coord.ImageLine(line: list[ImageCoord] | LineString)

parallel_offset(distance: float) → ImageLine

Calculates a line that is the parallel offset of this line

to_world_line(tile_coord: TileCoord, config: Config) → WorldLine

Converts the line into a WorldLine

Parameters:

• tile_coord – The tile coordinate that the coordinate is part of

• config – The configuration

class renderer.misc_types.coord.Line(coords: list[Coord])

Represents a 2-dimensional line

property bounds: Bounds[float]

Find the minimum and maximum x/y values in a list of coords.

property centroid: Coord

Finds the visual center

in_bounds(bounds: Bounds[int]) → bool

Finds whether any part of the LineString is entirely within a bound

parallel_offset(distance: float) → Line

Calculates a line that is the parallel offset of this line

to_tiles(z: ZoomParams) → list[TileCoord]

Generates tile coordinates from a list of regular coordinates.

class renderer.misc_types.coord.TileCoord(z: int, x: int, y: int)

Represents a tile coordinate in the form (z, x, y).

static bounds(tile_coords: list[TileCoord]) → Bounds[int]

Find the minimum and maximum x/y values in a set of TileCoords.

x: int

Represents x-coordinate

y: int

Represents y-coordinate

z: int

Represents zoom

class renderer.misc_types.coord.Vector(_x: float, _y: float)

Represents a 2-dimensional vector

as_tuple() → tuple[float, float]

Represent the coordinates as a tuple

dot(other: Vector) → float

Dot product

unit() → Self

Normalises the vector

class renderer.misc_types.coord.WorldCoord(_x: float, _y: float)

Represents a 2-dimensional coordinate in the world

tiles(zoom_params: ZoomParams) → list[TileCoord]

Returns all tiles in the form of tile coordinates that contain the provided regular coordinate.

to_image_coord(tile_coord: TileCoord, config: Config) → ImageCoord

Converts the coordinate to an ImageCoord

Parameters:

• tile_coord – The tile coordinate that the coordinate is part of

• config – The configuration

class renderer.misc_types.coord.WorldLine(line: list[WorldCoord] | LineString)

Represents a line in the world

parallel_offset(distance: float) → WorldLine

Calculates a line that is the parallel offset of this line

to_image_line(tile_coord: TileCoord, config: Config) → ImageLine

Converts the line into an ImageLine

Parameters:

• tile_coord – The tile coordinate that the coordinate is part of

• config – The configuration

class renderer.misc_types.pla2.Component(namespace: str, id: str, display_name: str, description: str, type: str, layer: float, nodes: WorldLine, tags: list[str], attrs: dict | None = None)

A component to be rendered

attrs: dict | None

Additional attributes of the component, will probably be used in newer versions

description: str

The description of the component

display_name: str

This will appear on the map itself, if the component type’s style has a Text layer

property fid: str

The full ID of the component (<namespace>-<id>)

static find_ends(components: list[Component]) → Bounds[float]

Finds the minimum and maximum X and Y values from a set of components

id: str

The ID of the component

layer: float

The layer of the component. Higher numbers mean further in front

namespace: str

The namespace that the coordinate belongs to

nodes: WorldLine

The nodes of the component

static rendered_in(components: list[Component], zoom_params: ZoomParams) → list[TileCoord]

Finds the tile coordinates that the list of components will be rendered in.

tags: list[str]

The tags of the component

type: str

The component type of the map

class renderer.misc_types.pla2.Pla2File(namespace: str, components: list[Component])

Represents a PLA2 file

components: list[Component]

The components in the file

static from_file(file: Path) → Pla2File

Load a PLA2 file from a path, can be either in JSON or MessagePack format

static from_json(file: Path) → Pla2File

Load a PLA2 file, must be in JSON

static from_msgpack(file: Path) → Pla2File

Load a PLA2 file, must be in MessagePack

property ids: list[str]

A list of IDs that all the components have

namespace: str

The namespace of the file, all components included belong to this namespace

save_json(directory: Path) → None

Save the PLA2 file in JSON format to a directory

save_msgpack(directory: Path) → None

Save the PLA2 file in MessagePack format to a directory

static validate(comps: list[Component]) → list[Component]

Check for duplicate IDs in a list of components and returns the same list of components if all is well

Raises:

ValueError – If a duplicated ID is found

renderer.misc_types.skin_builder.CS

alias of ComponentStyle

renderer.misc_types.skin_builder.CTI

alias of ComponentTypeInfo

class renderer.misc_types.skin_builder.SkinBuilder(tile_size: int, fonts: dict[str, list[Path]], background: int)

Utility class for building skins.

class ComponentTypeInfo(shape: Literal['point', 'line', 'area'], tags: list[str] | None = None)

Utility class for building the component type info for the skin.

class ComponentStyle

Utility class for building the component style for the component.

json() → dict

Returns a JSON representation of the skin.

shape: Literal['point', 'line', 'area']

The shape of the component. Must be either point, line or area.

style: dict[str, list[ComponentStyle]]

The registered styles for the component type information

tags: list[str]

A list of tags for the component

background: str

The colour of the background in hexadecimal.

fonts: dict[str, list[Path]]

Keys are the formatting, eg “”, “b”, “i”, “bi”, values are the relative paths to the fonts.

json() → dict

Returns a JSON representation of the skin.

tile_size: int

Size of the tiles that the skin produces.

types: dict[str, CTI]

The component types that have been registered.

renderer.misc_types.skin_builder.blend(h1: int, h2: int, prop: float = 0.5) → int

Blend two colours together

Parameters:

• h1 – The first colour

• h2 – The second colour

• prop – The proportion of the second colour, between 0.0 and 1.0

renderer.misc_types.skin_builder.brighten(h1: int, strength: float = 0.5) → int

Lighten a colour

Parameters:

• h1 – The colour

• strength – The strength of the brightening, between 0.0 and 1.0

renderer.misc_types.skin_builder.darken(h1: int, strength: float = 0.5) → int

Darken a colour

Parameters:

• h1 – The colour

• strength – The strength of the darkening, between 0.0 and 1.0

renderer.misc_types.skin_builder.hex_to_colour(h: int) → str

renderer.misc_types.skin_builder.hex_to_colour(h: None) → None

Converts a hex colour, represented as an integer, into a string of format #XXXXXX :param h: The hex code (0xXXXXXX)

class renderer.misc_types.zoom_params.ZoomParams(min: int, max: int, range: float)

Utility object for storing zoom parameters.

Raises:

ValueError – If min > max

max: int

Maximum zoom value

min: int

Minimum zoom value

range: float

Actual distance covered by a tile in the maximum zoom

Skin

class renderer.skin_type.ComponentStyle(json: dict | None = None, tags: list[str] | None = None, shape: Literal['point', 'line', 'area'] | None = None)

Represents the styles portion of a ComponentTypeInfo. Base class for all types of ComponentStyle.

Parameters:

• json – JSON dictionary as input

• type_info – The type_info that the ComponentStyle is under

render(component: Component, imd: ImageDraw.ImageDraw, img: Image.Image, consts: Part1Consts, tile_coord: TileCoord) → None

Renders the component into an ImageDraw instance.

class renderer.skin_type.ComponentTypeInfo(name: str, json: SkinType, order: list[str])

An object representing a component type in the types portion of a skin.

Parameters:

• name – Will set name

• json – The JSON of the component type

• order – Will set _order

name: str

The name of the component.

shape: Literal['point', 'line', 'area']

The shape of the component, must be one of point, line, area

styles: dict[tuple[int, int], list[ComponentStyle]]

The styles of the object, denoted as {(max_zoom, min_zoom): [style, ...]}

tags: list[str]

The list of tags attributed to the component.

class renderer.skin_type.Skin(json: SkinJson)

Represents a skin.

Parameters:

json – The JSON of the skin.

classmethod from_name(name: str = 'default') → Skin

Gets a skin from inside the package.

Raises:

FileNotFoundError – If skin does not exist

get_font(style: str, size: int, assets_dir: Path, rendered_text: str = '') → FreeTypeFont

Gets a font, given the style and size.

Parameters:

• style – The style of the font needed, eg. Bold, italic etc.

• size – The size of the font

• assets_dir – Where the font is stored

• rendered_text – The text that is rendered with the font, to allow for fallbacks

Raises:

FileNotFoundError – If font is not found

static validate_json(json: SkinJson) → Literal[True]

Validates a skin JSON file.

class renderer.skin_type.point.PointCircle(json: dict | None = None, tags: list[str] | None = None, shape: Literal['point', 'line', 'area'] | None = None)

Represents a circle of a point

render(component: Component, imd: ImageDraw.ImageDraw, _: Image.Image, consts: Part1Consts, tile_coord: TileCoord) → None

Renders the component into an ImageDraw instance.

class renderer.skin_type.point.PointImage(json: dict | None = None, tags: list[str] | None = None, shape: Literal['point', 'line', 'area'] | None = None)

Represents an image of a point

render(component: Component, _: ImageDraw.ImageDraw, img: Image.Image, consts: Part1Consts, tile_coord: TileCoord) → None

Renders the component into an ImageDraw instance.

class renderer.skin_type.point.PointSquare(json: dict | None = None, tags: list[str] | None = None, shape: Literal['point', 'line', 'area'] | None = None)

Represents a square of a point

render(component: Component, imd: ImageDraw.ImageDraw, _: Image.Image, consts: Part1Consts, tile_coord: TileCoord) → None

Renders the component into an ImageDraw instance.

class renderer.skin_type.point.PointText(json: dict | None = None, tags: list[str] | None = None, shape: Literal['point', 'line', 'area'] | None = None)

Represents a text of a point

render(component: Component, imd: ImageDraw.ImageDraw, img: Image.Image, consts: Part1Consts, tile_coord: TileCoord) → None

Renders the component into an ImageDraw instance.

class renderer.skin_type.line.LineBack(json: dict | None = None, tags: list[str] | None = None, shape: Literal['point', 'line', 'area'] | None = None)

Represent the back layer of a line

class renderer.skin_type.line.LineFore(json: dict | None = None, tags: list[str] | None = None, shape: Literal['point', 'line', 'area'] | None = None)

Represents the front layer of a line

render(component: Component, imd: ImageDraw.ImageDraw, _: Image.Image, consts: Part1Consts, tile_coord: TileCoord) → None

Renders the component into an ImageDraw instance.

class renderer.skin_type.line.LineText(json: dict | None = None, tags: list[str] | None = None, shape: Literal['point', 'line', 'area'] | None = None)

Represents text of a point

render(component: Component, _: ImageDraw.ImageDraw, img: Image.Image, consts: Part1Consts, tile_coord: TileCoord) → None

Renders the component into an ImageDraw instance.

class renderer.skin_type.area.AreaBorderText(json: dict | None = None, tags: list[str] | None = None, shape: Literal['point', 'line', 'area'] | None = None)

Represent the border text of an area

render(component: Component, imd: ImageDraw.ImageDraw, img: Image.Image, consts: Part1Consts, tile_coord: TileCoord) → None

Renders the component into an ImageDraw instance.

class renderer.skin_type.area.AreaCenterImage(json: dict | None = None, tags: list[str] | None = None, shape: Literal['point', 'line', 'area'] | None = None)

Represents the image at the centre of an area

render(component: Component, _: ImageDraw.ImageDraw, img: Image.Image, consts: Part1Consts, tile_coord: TileCoord) → None

Renders the component into an ImageDraw instance.

class renderer.skin_type.area.AreaCenterText(json: dict | None = None, tags: list[str] | None = None, shape: Literal['point', 'line', 'area'] | None = None)

Represents the text at the centre of an area

render(component: Component, imd: ImageDraw.ImageDraw, img: Image.Image, consts: Part1Consts, tile_coord: TileCoord) → None

Renders the component into an ImageDraw instance.

class renderer.skin_type.area.AreaFill(json: dict | None = None, tags: list[str] | None = None, shape: Literal['point', 'line', 'area'] | None = None)

Represents the fill and outline of an area

render(component: Component, imd: ImageDraw.ImageDraw, img: Image.Image, consts: Part1Consts, tile_coord: TileCoord) → None

Renders the component into an ImageDraw instance.

Math Utils

renderer.math_utils.dash(coords: ImageLine, dash_length: float, gap_length: float) → list[ImageLine]

Takes a list of coordinates and returns a list of lines that make up a dashed line.

Parameters:

• coords – The list of coordinates

• dash_length (float) – the length of each dash

• gap_length (float) – the length of the gap between dashes

renderer.math_utils.rotate_around_pivot(coord: Coord, pivot: Coord, theta: float) → Coord

Rotates a set of coordinates about a pivot point.

Parameters:

• coord (float) – The coordinate to be rotated

• pivot (float) – The pivot to be rotated about

• theta (float) – The angle to rotate in radians

renderer.math_utils.segments_intersect(c1: Coord, c2: Coord, c3: Coord, c4: Coord) → bool

Finds if two segments intersect.

Parameters:

• c1 – The 1st point of the 1st segment.

• c2 – The 2nd point of the 1st segment.

• c3 – The 1st point of the 2nd segment.

• c4 – The 2nd point of the 2nd segment.

Other Utils

renderer.merge_tiles.merge_tiles(images: Path | dict[TileCoord, Image], save_dir: Path | None = None, zoom: list[int] | None = None) → dict[int, Image]

Merges tiles rendered by render().

Parameters:

• images – Give in the form of (tile coord): (PIL Image), like the return value of render(), or as a path to a directory.

• save_dir – The directory to save the merged images in

• zoom – If left empty, automatically calculates all zoom values based on tiles; otherwise, the layers of zoom to merge.

renderer.pla1to2.pla1to2(old_comps: dict[str, Pla1ComponentJson], old_nodes: dict[str, Pla1NodeJson]) → list[Pla2File]

Converts PLA1 to PLA2

Parameters:

• old_comps – The components JSON of PLA1

• old_nodes – The nodes JSON of PLA1