Reference

renderer.__version__: str: The version.

Main

renderer.render(components: renderer.objects.components.ComponentList, nodes: renderer.objects.nodes.NodeList, min_zoom: int, max_zoom: int, max_zoom_range: typing.Union[int, float], skin: renderer.objects.skin.Skin = <renderer.objects.skin.Skin object>, save_images: bool = True, save_dir: pathlib.Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/tile-renderer/checkouts/v2.0/docs'), assets_dir: pathlib.Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/tile-renderer/checkouts/v2.0/renderer/skins/assets'), processes: int = 2, tiles: typing.Optional[typing.List[renderer.types.TileCoord]] = None, offset: typing.Tuple[typing.Union[int, float], typing.Union[int, float]] = (0, 0), use_ray: bool = True) → Dict[renderer.types.TileCoord, PIL.Image.Image]

Renders tiles from given coordinates and zoom values.

Warning

Run this function under if __name__ == "__main__" if use_ray is False, or else there would be a lot of multiprocessing RuntimeErrors.

Parameters

components (ComponentList) – a JSON of components
nodes (NodeList) – a JSON of nodes
min_zoom (int) – minimum zoom value
max_zoom (int) – maximum zoom value
max_zoom_range (RealNum) – actual distance covered by a tile in the maximum zoom
skin (Skin) – The skin to use for rendering the tiles
save_images (int) – whether to save the tile images in a folder or not
save_dir (Path) – the directory to save tiles in
assets_dir (Path) – the asset directory for the skin
processes (int) – The amount of processes to run for rendering
tiles (list[TileCoord] | None) – a list of tiles to render
offset (tuple[RealNum, RealNum]) – the offset to shift all node coordinates by, given as (x,y)
use_ray (bool) – Whether to use Ray multiprocessing instead of the internal multiprocessing module.

Returns

Given in the form of {tile_coord: image}

Return type

dict[TileCoord, Image.Image]

Raises

ValueError – if max_zoom < min_zoom

renderer.merge_tiles(images: Union[str, Dict[renderer.types.TileCoord, PIL.Image.Image]], save_images: bool = True, save_dir: pathlib.Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/tile-renderer/checkouts/v2.0/docs'), zoom: Optional[List[int]] = None) → Dict[int, PIL.Image.Image]

Merges tiles rendered by render().

Parameters

images (str | dict[TileCoord, Image]) – Give in the form of (tile coord): (PIL Image), like the return value of render(), or as a path to a directory.
save_images (bool) – whether to save the tile images in a folder or not
save_dir (Path) – the directory to save tiles in
zoom (list[int] | None) – if left empty, automatically calculates all zoom values based on tiles; otherwise, the layers of zoom to merge.

Returns

Given in the form of (Zoom): (PIL Image)

Return type

dict[int, Image.Image]

Tools

renderer.tools.components.find_ends(components: renderer.objects.components.ComponentList, nodes: renderer.objects.nodes.NodeList) → Tuple[Union[int, float], Union[int, float], Union[int, float], Union[int, float]]

Finds the minimum and maximum X and Y values of a JSON of components

Parameters

components (ComponentList) – a JSON of components
nodes (NodeList) – a JSON of nodes

Returns

Returns in the form (x_max, x_min, y_max, y_min)

Return type

Tuple[RealNum, RealNum, RealNum, RealNum]

renderer.tools.components.rendered_in(components: renderer.objects.components.ComponentList, nodes: renderer.objects.nodes.NodeList, min_zoom: int, max_zoom: int, max_zoom_range: Union[int, float]) → List[renderer.types.TileCoord]

Like tools.line.to_tiles(), but for a JSON of components.

Parameters

components (ComponentList) – a JSON of components
nodes (NodeList) – a JSON of nodes
min_zoom (int) – minimum zoom value
max_zoom (int) – maximum zoom value
max_zoom_range (RealNum) – actual distance covered by a tile in the maximum zoom

Returns

A list of tile coordinates

Return type

List[TileCoord]

Raises

ValueError – if max_zoom < min_zoom

renderer.tools.components.to_geo_json(component_json: Dict[str, renderer.types.ComponentJson], node_json: Dict[str, renderer.types.NodeJson], skin_json: renderer.types.SkinJson) → dict

Converts component JSON into GeoJson (with nodes and skin).

Parameters

component_json (ComponentListJson) – a JSON of components
node_json (NodeListJson) – a JSON of nodes
skin_json (SkinJson) – a JSON of the skin

Returns

A GeoJson dictionary

Return type

dict

renderer.tools.coord.to_tiles(coord: renderer.types.Coord, min_zoom: int, max_zoom: int, max_zoom_range: Union[int, float]) → List[renderer.types.TileCoord]

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

Parameters

coord (Coord) – Coordinates provided in the form (x,y)
min_zoom (int) – minimum zoom value
max_zoom (int) – maximum zoom value
max_zoom_range (RealNum) – actual distance covered by a tile in the maximum zoom

Returns

A list of tile coordinates

Return type

List[TileCoord]

Raises

ValueError – if max_zoom < min_zoom

renderer.tools.geo_json.to_component_node_json(geo_json: dict) → Tuple[Dict[str, renderer.types.ComponentJson], Dict[str, renderer.types.NodeJson]]

Converts GeoJson to component and node JSONs.

Parameters: geo_json (dict) – a GeoJson dictionary
Returns: Components and nodes
Return type: Tuple[ComponentListJson, NodeListJson]

renderer.tools.line.find_ends(coords: List[renderer.types.Coord]) → Tuple[Union[int, float], Union[int, float], Union[int, float], Union[int, float]]

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

Parameters: coords (List[Coord]) – a list of coordinates, provide in a tuple of (x,y)
Returns: Returns in the form (x_max, x_min, y_max, y_min)
Return type: Tuple[RealNum, RealNum, RealNum, RealNum]

renderer.tools.line.to_tiles(coords: List[renderer.types.Coord], min_zoom: int, max_zoom: int, max_zoom_range: Union[int, float]) → List[renderer.types.TileCoord]

Generates tile coordinates from list of regular coordinates using tools.coord.to_tiles(). Mainly for rendering whole components.

Parameters

coords (List[Coord]) – of coordinates in tuples of (x,y)
min_zoom (int) – minimum zoom value
max_zoom (int) – maximum zoom value
max_zoom_range (RealNum) – range of coordinates covered by a tile in the maximum zoom (how do I phrase this?) For example, a max_zoom of 5 and a max_zoomValue of 8 will make a 5-zoom tile cover 8 units

Returns

A list of tile coordinates

Return type

List[TileCoord]

Raises

ValueError – if max_zoom < min_zoom
ValueError – if empty list of coords given

renderer.tools.nodes.find_components_attached(node_id: str, components: renderer.objects.components.ComponentList) → List[Tuple[renderer.objects.components.Component, int]]

Finds which components attach to a node.

Parameters

node_id (str) – the node to search for
components (ComponentList) – a list of components

Returns

A list of tuples in the form of (component_id, index)

Return type

List[Tuple[str, int]]

renderer.tools.nodes.to_coords(nodes: List[str], node_list: renderer.objects.nodes.NodeList) → List[renderer.types.Coord]

Converts a list of nodes IDs into a list of coordinates with a JSON of nodes as its reference.

Parameters

nodes (List[str]) – a list of node IDs
node_list (NodeList) – a JSON of nodes

Returns

A list of coordinates

Return type

List[Coord]

Raises

KeyError – if a node does not exist

renderer.tools.tile.find_ends(coords: List[renderer.types.TileCoord]) → Tuple[Union[int, float], Union[int, float], Union[int, float], Union[int, float]]

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

Parameters: coords (List[TileCoord]) – a list of tile coordinates, provide in a tuple of (z,x,y)
Returns: Returns in the form (x_max, x_min, y_max, y_min)
Return type: Tuple[RealNum, RealNum, RealNum, RealNum]

Math Tools

renderer.mathtools.dash(x1: Union[int, float], y1: Union[int, float], x2: Union[int, float], y2: Union[int, float], d: Union[int, float], g: Union[int, float], o: Union[int, float] = 0, empty_start: bool = False) → List[List[renderer.types.Coord]]

Finds points along a segment that are a specified distance apart.

Parameters

x1 (RealNum) – the x-coordinate of the 1st point
y1 (RealNum) – the y-coordinate of the 1st point
x2 (RealNum) – the x-coordinate of the 2nd point
y2 (RealNum) – the y-coordinate of the 2nd point
d (RealNum) – the length of a single dash
g (RealNum) – the length of the gap between dashes
o (RealNum) – the offset from (x1,y1) towards (x2,y2) before dashes are calculated
empty_start (bool) – Whether to start the line from (x1,y1) empty before the start of the next dash

Returns

A list of points along the segment, given in [[(x1, y1), (x2, y2)], etc]

Return type

list[list[Coord]]

renderer.mathtools.dash_offset(coords: List[renderer.types.Coord], d: Union[int, float], g: Union[int, float]) → List[Tuple[Union[int, float], bool]]

Calculates the offsets on each coord of a line for a smoother dashing sequence.

Parameters

coords (List[Coord]) – the coords of the line
d (RealNum) – the length of a single dash
g (RealNum) – the length of the gap between dashes

Returns

The offsets of each coordinate, and whether to start the next segment with empty_start, given in (offset, empty_start)

Return type

list[tuple[RealNum, bool]]

renderer.mathtools.line_in_box(line: List[renderer.types.Coord], top: Union[int, float], bottom: Union[int, float], left: Union[int, float], right: Union[int, float]) → bool

Finds if any nodes of a line go within the box.

Parameters

line (list[Coord]) – the line to check for
top (RealNum) – the bounds of the box
bottom (RealNum) – the bounds of the box
left (RealNum) – the bounds of the box
right (RealNum) – the bounds of the box

Returns

Whether any nodes of a line go within the box.

Return type

bool

renderer.mathtools.lines_intersect(x1: Union[int, float], y1: Union[int, float], x2: Union[int, float], y2: Union[int, float], x3: Union[int, float], y3: Union[int, float], x4: Union[int, float], y4: Union[int, float]) → bool

Finds if two segments intersect.

Parameters

x1 (RealNum) – the x-coordinate of the 1st point of the 1st segment.
y1 (RealNum) – the y-coordinate of the 1st point of the 1st segment.
x2 (RealNum) – the x-coordinate of the 2nd point of the 1st segment.
y2 (RealNum) – the y-coordinate of the 2nd point of the 1st segment.
x3 (RealNum) – the x-coordinate of the 1st point of the 2nd segment.
y3 (RealNum) – the y-coordinate of the 1st point of the 2nd segment.
x4 (RealNum) – the x-coordinate of the 2nd point of the 2nd segment.
y4 (RealNum) – the y-coordinate of the 2nd point of the 2nd segment.

Returns

Whether the two segments intersect.

Return type

bool

renderer.mathtools.midpoint(x1: Union[int, float], y1: Union[int, float], x2: Union[int, float], y2: Union[int, float], o: Union[int, float], n: int = 1, return_both: bool = False) → Union[List[Tuple[renderer.types.Coord, Union[int, float]]], List[List[Tuple[renderer.types.Coord, Union[int, float]]]]]

Calculates the midpoint of two lines, offsets the distance away from the line, and calculates the rotation of the line.

Parameters

x1 (RealNum) – the x-coordinate of the 1st point
y1 (RealNum) – the y-coordinate of the 1st point
x2 (RealNum) – the x-coordinate of the 2nd point
y2 (RealNum) – the y-coordinate of the 2nd point
o (RealNum) – the offset from the line. If positive, the point above the line is returned; if negative, the point below the line is returned
n (int) – the number of midpoints on a single segment
return_both (bool) – if True, it will return both possible points.

Returns

A list of (lists of, when return_both=True) tuples in the form of (x, y, rot)

Return type

list[tuple[Coord, RealNum]] when return_both=False, list[list[tuple[Coord, RealNum]]] when return_both=True

renderer.mathtools.point_in_poly(xp: Union[int, float], yp: Union[int, float], coords: List[renderer.types.Coord]) → bool

Finds if a point is in a polygon.

Parameters

xp (RealNum) – the x-coordinate of the point.
yp (RealNum) – the y-coordinate of the point.
coords (list[Coord]) – the coordinates of the polygon; give in (x,y)

Returns

Whether the point is inside the polygon.

Return type

bool

renderer.mathtools.points_away(x: Union[int, float], y: Union[int, float], d: Union[int, float], m: Optional[Union[int, float]]) → List[renderer.types.Coord]

Finds two points that are a specified distance away from a specified point, all on a straight line.

Parameters

x (RealNum) – the x-coordinate of the original point
y (RealNum) – the y-coordinate of the original point
d (RealNum) – the distance the two points from the original point
m (RealNum | None) – the gradient of the line. Give None for a gradient of undefined.

Returns

Given in [(x1, y1), (x2, y2)]

Return type

list[Coord]

renderer.mathtools.poly_center(coords: List[renderer.types.Coord]) → renderer.types.Coord

Finds the center point of a polygon.

Parameters: coords (list[Coord]) – the coordinates of the polygon; give in (x,y)
Returns: The center of the polygon, given in (x,y)
Return type: Coord

renderer.mathtools.rotate_around_pivot(x: Union[int, float], y: Union[int, float], px: Union[int, float], py: Union[int, float], theta: Union[int, float]) → renderer.types.Coord

Rotates a set of coordinates around a pivot point.

Parameters

x (RealNum) – the x-coordinate to be rotated
y (RealNum) – the y-coordinate to be rotated
px (RealNum) – the x-coordinate of the pivot
py (RealNum) – the y-coordinate of the pivot
theta (RealNum) – how many degrees to rotate

Returns

The rotated coordinates, given in (x,y)

Return type

Coord

Validate

renderer.validate.v_coords(coords: List[renderer.types.Coord]) → Literal[True]

Validates a list of coordinates.

Parameters: coords (list[Coord]) – a list of coordinates.
Returns: Returns True if no errors

renderer.validate.v_geo_json(geo_json: dict) → Literal[True]

Validates a GeoJson file.

Parameters: geo_json (dict) – the GeoJson file
Returns: Returns True if no errors

renderer.validate.v_node_list(nodes: List[str], all_nodes: renderer.objects.nodes.NodeList) → Literal[True]

Validates a list of node IDs.

Parameters

nodes (list[str]) – a list of node IDs.
all_nodes (NodeList) – a dictionary of nodes

Returns

Returns True if no errors

renderer.validate.v_tile_coords(tiles: List[renderer.types.TileCoord], min_zoom: int, max_zoom: int) → Literal[True]

Validates a list of tile coordinates.

Parameters

tiles (list[TileCoord]) – a list of tile coordinates.
min_zoom (int) – minimum zoom value
max_zoom (int) – maximum zoom value

Returns

Returns True if no errors

Types

class renderer.types.ComponentJson(*args, **kwargs): Represents a component JSON object.

renderer.types.ComponentListJson

Represents a component list JSON.

alias of Dict[str, renderer.types.ComponentJson]

class renderer.types.Coord(x: Union[int, float], y: Union[int, float])

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

x: Union[int, float]: Alias for field number 0

y: Union[int, float]: Alias for field number 1

class renderer.types.NodeJson(*args, **kwargs): Represents a node JSON object.

renderer.types.NodeListJson

Represents a node list JSON.

alias of Dict[str, renderer.types.NodeJson]

renderer.types.RealNum

Represents a real number, either an integer or float.

alias of Union[int, float]

class renderer.types.SkinInfo(*args, **kwargs): Represents the info portion of a skin JSON.

class renderer.types.SkinJson(*args, **kwargs): Represents a skin JSON.

class renderer.types.SkinType(*args, **kwargs): Represents a component type in the types portion of a skin JSON.

class renderer.types.TileCoord(z: int, x: int, y: int)

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

x: int: Alias for field number 1

y: int: Alias for field number 2

z: int: Alias for field number 0

Objects

class renderer.objects.components.Component(name: str, json: renderer.types.ComponentJson)

A representation of a component.

Parameters

name (str) – Will set name.
json (ComponentJson) – The JSON of the component.

attrs: dict: A dictionary of attributes.

description: str: The component’s internal description.

displayname: str: The component’s display name.

hollows: List[str]: A list of hollow areas, if the type is area.

layer: RealNum: The layer of the component.

name: str: The name of the component in the main component list.

nodes: list[str]: The list of nodes that the component is anchored on.

tags: List[str]: A list of tags appended at the end of the component’s type.

type: str: The type of the component.

class renderer.objects.components.ComponentList(component_json: Dict[str, renderer.types.ComponentJson], node_json: Dict[str, renderer.types.NodeJson])

A list of components.

Parameters

component_json (ComponentListJson) – The JSON of the list of components.
node_json (NodeListJson) – The JSON of the list of nodes for validation.

component_ids() → List[str]

Gets all the component IDs.

Return type: List[str]

component_values() → List[renderer.objects.components.Component]

Gets all the component values.

Return type: List[Component]

components: Dict[str, renderer.objects.components.Component]: A dictionary of component objects, in the form of {id: component}.

static validate_json(component_json: dict, node_json: dict) → Literal[True]

Validates a JSON of components.

Parameters

component_json (ComponentListJson) – a dictionary of components
node_json (NodeListJson) – a dictionary of nodes

Returns

Returns True if no errors

class renderer.objects.nodes.Node(json: renderer.types.NodeJson)

A representation of a node.

Parameters: json (NodeJson) – The JSON of the node.

connections: list: Currently useless, will be used soon tm

x: Union[int, float]: The x coordinate of the node.

y: Union[int, float]: The y coordinate of the node.

class renderer.objects.nodes.NodeList(json: Dict[str, renderer.types.NodeJson])

A list of nodes.

Parameters: json (NodeListJson) – The JSON of the list of nodes.

node_ids() → List[str]

Gets all the node IDs.

Return type: List[str]

node_values() → List[renderer.objects.nodes.Node]

Gets all the node values.

Return type: List[Node]

nodes: Dict[str, renderer.objects.nodes.Node]: A dictionary of node objects, in the form {id: node}

static validate_json(json: dict) → Literal[True]

Validates a JSON of nodes.

Parameters: json (NodeListJson) – a dictionary of nodes
Returns: Returns True if no errors

class renderer.objects.skin.Skin(json: renderer.types.SkinJson)

Represents a skin.

Parameters: json (SkinJson) – The JSON of the skin.

class ComponentTypeInfo(name: str, json: renderer.types.SkinType, order: List[str])

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

Parameters

name (str) – Will set name
json (SkinType) – The JSON of the component type
order (List[str]) – Will set _order

class ComponentStyle(json: dict)

Represents the styles portion of a ComponentTypeInfo.

Parameters: json (dict) – The JSON of the styles

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[renderer.objects.skin.Skin.ComponentTypeInfo.ComponentStyle]]: The styles of the object, denoted as {(max_zoom, min_zoom): [style, ...]}

tags: List[str]: The list of tags attributed to the component.

classmethod from_name(name: str = 'default') → renderer.objects.skin.Skin

Gets a skin from inside the package.

Parameters: name (str) – the name of the skin
Returns: The skin
Return type: Skin
Raises: FileNotFoundError – if skin does not exist

get_font(style: str, size: int, assets_dir: pathlib.Path) → PIL.ImageFont.FreeTypeFont

Gets a font, given the style and size.

Parameters

style (str) – The style of the font needed, eg. bold, italic etc
size (int) – The size of the font
assets_dir (Path) – Where the font is stored

Returns

The font

Return type

ImageFont.FreeTypeFont

Raises

FileNotFoundError – if font is not found

static validate_json(json: dict) → Literal[True]

Validates a skin JSON file.

Parameters: json (SkinJson) – the skin JSON file
Returns: Returns True if no errors