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__"
ifuse_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 ofrender()
, 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 amax_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.
- 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.
- 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
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.
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
isarea
.
- 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
- 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