environmentaltools.download.create_osm_image

environmentaltools.download.create_osm_image(lon: float, lat: float, site_name: str = 'Location', style: Literal['map', 'satellite'] = 'satellite', distance_x: float = 500, distance_y: float = 500, output_file: str | None = None, show_plot: bool = True) → None[source]

Create and display an OpenStreetMap image with customizable style and extent.

This function downloads OpenStreetMap tiles (either satellite imagery or street map) and displays them using matplotlib with cartopy projections. The zoom level is automatically calculated based on the requested extent.

Parameters:

  • lon – Longitude of the center point in degrees.

  • lat – Latitude of the center point in degrees.

  • site_name – Name of the site/location for the plot title. Default is “Location”.

  • style – Map style, either ‘map’ for street map or ‘satellite’ for satellite imagery. Default is ‘satellite’.

  • distance_x – Distance from center to edge in the x-direction (meters). Default is 500.

  • distance_y – Distance from center to edge in the y-direction (meters). Default is 500.

  • output_file – Path to save the image file. If None, image is not saved. Supported formats: .png, .jpg, .jpeg, .pdf, .svg, .eps

  • show_plot – Whether to display the plot interactively. Default is True.

Returns:

None. Displays and/or saves the map.

Notes

  • Scale (zoom level) is automatically calculated based on the maximum distance.

  • According to OSM policies, avoid both large scale (>16) and large radius (>1000).

  • Scale guidelines:

    • 2: Coarse image for worldwide or continental scales

    • 4-6: Medium coarseness for countries and larger states

    • 6-10: Medium fineness for smaller states, regions, and cities

    • 10-12: Fine image for city boundaries and zip codes

    • 14+: Extremely fine image for roads, blocks, buildings

References

OSM Tile Usage Policy: https://operations.osmfoundation.org/policies/tiles/