voxcity.geoprocessor.draw¶

Draw subpackage — interactive map drawing and editing tools for VoxCity.

This package provides functions for: - Drawing and rotating rectangles on interactive maps - City-centred map initialisation with fixed-dimension rectangles - Building footprint visualisation and polygon drawing - Interactive building, tree, and land-cover editors

Submodules¶

rectangle : Rectangle drawing/rotation utilities. polygon : Building display and polygon vertex extraction. edit_building : Interactive building height/footprint editor. edit_tree : Interactive tree canopy editor. edit_landcover: Interactive land-cover class editor. _common : Shared helpers, constants, GeoJSON builders (internal).

Submodules¶

Functions¶

`rotate_rectangle`(m, rectangle_vertices, angle)	Project rectangle to Mercator, rotate, and re-project to lat-lon coordinates.
`draw_rectangle_map`([center, zoom])	Create an interactive map for drawing rectangles with two modes.
`draw_rectangle_map_cityname`(cityname[, zoom])	Create an interactive map centered on a specified city for drawing rectangles.
`center_location_map_cityname`(cityname, ...[, zoom, ...])	Create a map centered on a city where clicking creates a rectangle of specified dimensions.
`rectangle_map`([center, zoom, width, height, cityname])	Create an interactive map with a side panel for drawing rectangles.
`create_rectangle_map`([cityname, zoom, width, height])	Create an interactive rectangle-drawing map with a side panel.
`display_buildings_and_draw_polygon`([voxcity, ...])	Display building footprints and enable polygon drawing on an interactive map.
`get_polygon_vertices`(drawn_polygons[, polygon_id])	Extract vertices from drawn polygons data structure.
`edit_building`([voxcity, building_gdf, initial_center, ...])	Interactive map editor: Draw rectangles, freehand polygons, and DELETE existing buildings.
`create_building_editor`([building_gdf, initial_center, ...])	Creates and displays an interactive building editor.
`edit_tree`([voxcity, initial_center, zoom])	Interactive map editor for trees.
`create_tree_editor`([tree_gdf, initial_center, zoom, ...])	Convenience wrapper to display the tree editor map.
`edit_landcover`([voxcity, initial_center, zoom])	Interactive map editor for land-cover classes.

Package Contents¶

voxcity.geoprocessor.draw.rotate_rectangle(m, rectangle_vertices, angle)[source]¶

Project rectangle to Mercator, rotate, and re-project to lat-lon coordinates.

The rotation is performed around the rectangle’s centroid using a standard 2D rotation matrix in Web Mercator space for accurate distance preservation.

Parameters:

m (ipyleaflet.Map) – Map object to draw the rotated rectangle on.
rectangle_vertices (list) – List of (lon, lat) tuples defining the rectangle.
angle (float) – Rotation angle in degrees (positive = counter-clockwise).

Returns:

Rotated (lon, lat) tuples, or None if no vertices provided.

Return type:

list

voxcity.geoprocessor.draw.draw_rectangle_map(center=(40, -100), zoom=4)[source]¶

Create an interactive map for drawing rectangles with two modes.

Aligned mode: click two opposite corners to draw an axis-aligned rectangle.
Rotated mode: click 3 points to draw a rotated rectangle.

Drawing starts immediately when a mode button is selected.

Parameters:

center (tuple) – Center coordinates (lat, lon). Defaults to (40, -100).
zoom (int) – Initial zoom level. Defaults to 4.

Returns:

(ipywidgets.VBox, list that will be populated with (lon, lat) vertices)

Return type:

tuple

voxcity.geoprocessor.draw.draw_rectangle_map_cityname(cityname, zoom=15)[source]¶

Create an interactive map centered on a specified city for drawing rectangles.

Two modes are available via toggle buttons:

Aligned: click two opposite corners (axis-aligned rectangle).
Rotated: click 3 points to draw a rotated rectangle.

Parameters:

cityname (str) – Name of the city (e.g. “Tokyo, Japan”).
zoom (int) – Initial zoom level. Defaults to 15.

Returns:

(ipywidgets.VBox, list that will be populated with (lon, lat) vertices)

Return type:

tuple

voxcity.geoprocessor.draw.center_location_map_cityname(cityname, east_west_length, north_south_length, zoom=15, rotation_angle=0)[source]¶

Create a map centered on a city where clicking creates a rectangle of specified dimensions.

After placing a center point, an interactive rotation slider appears so the rectangle can be rotated on the map in real time.

Parameters:

cityname (str) – Name of the city.
east_west_length (float) – Width of the rectangle in meters.
north_south_length (float) – Height of the rectangle in meters.
zoom (int) – Initial zoom level. Defaults to 15.
rotation_angle (float) – Initial rotation angle in degrees (positive = counter-clockwise). Defaults to 0.

Returns:

(widget, list that will be populated with (lon, lat) vertices): widget is an ipywidgets VBox containing the map and a rotation slider. Display it with display(widget) or as the last expression in a notebook cell.

Return type:

tuple

voxcity.geoprocessor.draw.rectangle_map(center=(40, -100), zoom=15, width=500, height=500, cityname='')[source]¶

Create an interactive map with a side panel for drawing rectangles.

Three drawing modes are provided via the panel:

Aligned: click two opposite corners for an axis-aligned rectangle.
Rotated: click 3 points to draw a rotated rectangle.
Fixed: click a center point to place a rectangle with the specified width (east-west) and height (north-south), then adjust the rotation angle with a slider.

The panel includes a city-name field that re-centres the map on submission.

Parameters:

center (tuple) – Map center as (lat, lon). Defaults to (40, -100).
zoom (int) – Initial zoom level. Defaults to 15.
width (float) – Initial east-west length in metres (for Fixed mode).
height (float) – Initial north-south length in metres (for Fixed mode).
cityname (str) – Pre-filled city name for the location field.

Returns:

(ipywidgets.VBox, list that will be populated with (lon, lat) vertices)

Return type:

tuple

voxcity.geoprocessor.draw.create_rectangle_map(cityname=None, zoom=15, width=500, height=500)[source]¶

Create an interactive rectangle-drawing map with a side panel.

Combines aligned / rotated drawing and fixed-dimension placement into a single map. If cityname is provided the map is centred on that city and the location field is pre-filled; otherwise a world-level view is shown and the user can type a city name into the panel.

Parameters:

cityname (str, optional) – Name of the city (e.g. "Tokyo").
zoom (int) – Initial zoom level. Defaults to 15.
width (float) – Initial east-west length in metres (for Fixed mode).
height (float) – Initial north-south length in metres (for Fixed mode).

Returns:

(ipywidgets.VBox, list that will be populated with (lon, lat): vertices in SW → NW → NE → SE order)

Return type:

tuple

voxcity.geoprocessor.draw.display_buildings_and_draw_polygon(voxcity=None, building_gdf=None, rectangle_vertices=None, zoom=17)[source]¶

Display building footprints and enable polygon drawing on an interactive map.

Parameters:

voxcity (VoxCity, optional) – VoxCity object to extract data from.
building_gdf (GeoDataFrame, optional) – Building footprints.
rectangle_vertices (list, optional) – [lon, lat] rectangle corners.
zoom (int) – Initial zoom level. Default=17.

Returns:

(Map, drawn_polygons list of dicts with ‘id’, ‘vertices’, ‘color’)

Return type:

tuple

voxcity.geoprocessor.draw.get_polygon_vertices(drawn_polygons, polygon_id=None)[source]¶

Extract vertices from drawn polygons data structure.

Parameters:

drawn_polygons – List returned from display_buildings_and_draw_polygon().
polygon_id (int, optional) – Specific polygon ID. If None, returns all.

Returns:

List of (lon, lat) tuples for the specified polygon, or list of lists for all.

voxcity.geoprocessor.draw.edit_building(voxcity=None, building_gdf=None, initial_center=None, zoom=17, rectangle_vertices=None)[source]¶

Interactive map editor: Draw rectangles, freehand polygons, and DELETE existing buildings.

Parameters:

voxcity (VoxCity, optional) – VoxCity object to extract data from.
building_gdf (GeoDataFrame, optional) – Existing buildings.
initial_center (tuple, optional) – (lon, lat) map center.
zoom (int) – Initial zoom level. Default=17.
rectangle_vertices (list, optional) – Rectangle corner coordinates.

Returns:

(Map, updated_gdf)

Return type:

tuple

voxcity.geoprocessor.draw.create_building_editor(building_gdf=None, initial_center=None, zoom=17, rectangle_vertices=None)[source]¶

Creates and displays an interactive building editor.

Returns:: Automatically-updating building GeoDataFrame.
Return type:: GeoDataFrame

voxcity.geoprocessor.draw.edit_tree(voxcity=None, initial_center=None, zoom=17)[source]¶

Interactive map editor for trees.

Users can add tree points, remove tree points, visualise the existing canopy grid, and remove canopy cells by clicking or drawing an area polygon.

Parameters:

voxcity (VoxCity, optional) – VoxCity object for data extraction.
initial_center (tuple, optional) – (lon, lat) for initial map center.
zoom (int) – Initial zoom level. Default=17.

Returns:

(map_object, updated_tree_gdf, canopy_top, canopy_bottom)

Return type:

tuple

voxcity.geoprocessor.draw.create_tree_editor(tree_gdf=None, initial_center=None, zoom=17, rectangle_vertices=None)[source]¶: Convenience wrapper to display the tree editor map.

voxcity.geoprocessor.draw.edit_landcover(voxcity=None, initial_center=None, zoom=17)[source]¶

Interactive map editor for land-cover classes.

Users can select a land-cover class from the palette and paint individual cells by clicking or in bulk by drawing an area polygon.

Parameters:

voxcity (VoxCity, optional) – VoxCity object for data extraction.
initial_center (tuple, optional) – (lon, lat) for initial map centre.
zoom (int) – Initial zoom level. Default=17.

Returns:

(map_object, land_cover_classes np.ndarray)

Return type:

tuple