voxcity.geoprocessor.draw ========================= .. py:module:: voxcity.geoprocessor.draw .. autoapi-nested-parse:: 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 ---------- .. toctree:: :maxdepth: 1 /autoapi/voxcity/geoprocessor/draw/edit_building/index /autoapi/voxcity/geoprocessor/draw/edit_landcover/index /autoapi/voxcity/geoprocessor/draw/edit_tree/index /autoapi/voxcity/geoprocessor/draw/polygon/index /autoapi/voxcity/geoprocessor/draw/rectangle/index Functions --------- .. autoapisummary:: voxcity.geoprocessor.draw.rotate_rectangle voxcity.geoprocessor.draw.draw_rectangle_map voxcity.geoprocessor.draw.draw_rectangle_map_cityname voxcity.geoprocessor.draw.center_location_map_cityname voxcity.geoprocessor.draw.rectangle_map voxcity.geoprocessor.draw.create_rectangle_map voxcity.geoprocessor.draw.display_buildings_and_draw_polygon voxcity.geoprocessor.draw.get_polygon_vertices voxcity.geoprocessor.draw.edit_building voxcity.geoprocessor.draw.create_building_editor voxcity.geoprocessor.draw.edit_tree voxcity.geoprocessor.draw.create_tree_editor voxcity.geoprocessor.draw.edit_landcover Package Contents ---------------- .. py:function:: rotate_rectangle(m, rectangle_vertices, angle) 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. :param m: Map object to draw the rotated rectangle on. :type m: ipyleaflet.Map :param rectangle_vertices: List of (lon, lat) tuples defining the rectangle. :type rectangle_vertices: list :param angle: Rotation angle in degrees (positive = counter-clockwise). :type angle: float :returns: Rotated (lon, lat) tuples, or None if no vertices provided. :rtype: list .. py:function:: draw_rectangle_map(center=(40, -100), zoom=4) 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. :param center: Center coordinates (lat, lon). Defaults to (40, -100). :type center: tuple :param zoom: Initial zoom level. Defaults to 4. :type zoom: int :returns: (ipywidgets.VBox, list that will be populated with (lon, lat) vertices) :rtype: tuple .. py:function:: draw_rectangle_map_cityname(cityname, zoom=15) 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. :param cityname: Name of the city (e.g. "Tokyo, Japan"). :type cityname: str :param zoom: Initial zoom level. Defaults to 15. :type zoom: int :returns: (ipywidgets.VBox, list that will be populated with (lon, lat) vertices) :rtype: tuple .. py:function:: center_location_map_cityname(cityname, east_west_length, north_south_length, zoom=15, rotation_angle=0) 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. :param cityname: Name of the city. :type cityname: str :param east_west_length: Width of the rectangle in meters. :type east_west_length: float :param north_south_length: Height of the rectangle in meters. :type north_south_length: float :param zoom: Initial zoom level. Defaults to 15. :type zoom: int :param rotation_angle: Initial rotation angle in degrees (positive = counter-clockwise). Defaults to 0. :type rotation_angle: float :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. :rtype: tuple .. py:function:: rectangle_map(center=(40, -100), zoom=15, width=500, height=500, cityname='') 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. :param center: Map center as (lat, lon). Defaults to (40, -100). :type center: tuple :param zoom: Initial zoom level. Defaults to 15. :type zoom: int :param width: Initial east-west length in metres (for Fixed mode). :type width: float :param height: Initial north-south length in metres (for Fixed mode). :type height: float :param cityname: Pre-filled city name for the location field. :type cityname: str :returns: (ipywidgets.VBox, list that will be populated with (lon, lat) vertices) :rtype: tuple .. py:function:: create_rectangle_map(cityname=None, zoom=15, width=500, height=500) 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. :param cityname: Name of the city (e.g. ``"Tokyo"``). :type cityname: str, optional :param zoom: Initial zoom level. Defaults to 15. :type zoom: int :param width: Initial east-west length in metres (for Fixed mode). :type width: float :param height: Initial north-south length in metres (for Fixed mode). :type height: float :returns: (ipywidgets.VBox, list that will be populated with (lon, lat) vertices in SW → NW → NE → SE order) :rtype: tuple .. py:function:: display_buildings_and_draw_polygon(voxcity=None, building_gdf=None, rectangle_vertices=None, zoom=17) Display building footprints and enable polygon drawing on an interactive map. :param voxcity: VoxCity object to extract data from. :type voxcity: VoxCity, optional :param building_gdf: Building footprints. :type building_gdf: GeoDataFrame, optional :param rectangle_vertices: [lon, lat] rectangle corners. :type rectangle_vertices: list, optional :param zoom: Initial zoom level. Default=17. :type zoom: int :returns: (Map, drawn_polygons list of dicts with 'id', 'vertices', 'color') :rtype: tuple .. py:function:: get_polygon_vertices(drawn_polygons, polygon_id=None) Extract vertices from drawn polygons data structure. :param drawn_polygons: List returned from display_buildings_and_draw_polygon(). :param polygon_id: Specific polygon ID. If None, returns all. :type polygon_id: int, optional :returns: List of (lon, lat) tuples for the specified polygon, or list of lists for all. .. py:function:: edit_building(voxcity=None, building_gdf=None, initial_center=None, zoom=17, rectangle_vertices=None) Interactive map editor: Draw rectangles, freehand polygons, and DELETE existing buildings. :param voxcity: VoxCity object to extract data from. :type voxcity: VoxCity, optional :param building_gdf: Existing buildings. :type building_gdf: GeoDataFrame, optional :param initial_center: (lon, lat) map center. :type initial_center: tuple, optional :param zoom: Initial zoom level. Default=17. :type zoom: int :param rectangle_vertices: Rectangle corner coordinates. :type rectangle_vertices: list, optional :returns: (Map, updated_gdf) :rtype: tuple .. py:function:: create_building_editor(building_gdf=None, initial_center=None, zoom=17, rectangle_vertices=None) Creates and displays an interactive building editor. :returns: Automatically-updating building GeoDataFrame. :rtype: GeoDataFrame .. py:function:: edit_tree(voxcity=None, initial_center=None, zoom=17) 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. :param voxcity: VoxCity object for data extraction. :type voxcity: VoxCity, optional :param initial_center: (lon, lat) for initial map center. :type initial_center: tuple, optional :param zoom: Initial zoom level. Default=17. :type zoom: int :returns: (map_object, updated_tree_gdf, canopy_top, canopy_bottom) :rtype: tuple .. py:function:: create_tree_editor(tree_gdf=None, initial_center=None, zoom=17, rectangle_vertices=None) Convenience wrapper to display the tree editor map. .. py:function:: edit_landcover(voxcity=None, initial_center=None, zoom=17) 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. :param voxcity: VoxCity object for data extraction. :type voxcity: VoxCity, optional :param initial_center: (lon, lat) for initial map centre. :type initial_center: tuple, optional :param zoom: Initial zoom level. Default=17. :type zoom: int :returns: (map_object, land_cover_classes np.ndarray) :rtype: tuple