overturetoosm
overturetoosm
is a Python package to convert objects tagged in the
Overture schema for use in OSM. Only Overture's places
and buildings
layers are currently supported.
Links:
1"""`overturetoosm` is a Python package to convert objects tagged in the 2Overture schema for use in OSM. Only Overture's `places` and `buildings` 3layers are currently supported. 4 5Links: 6* [Project GitHub](https://github.com/whubsch/overturetoosm) 7* [Documentation](https://whubsch.github.io/overturetoosm/) 8* [PyPI](https://pypi.org/project/overturetoosm/) 9""" 10 11from .places import process_place 12from .buildings import process_building 13from .utils import process_geojson 14from . import places 15from . import buildings 16from . import objects 17from . import utils 18from . import resources 19 20__all__ = [ 21 "process_place", 22 "process_building", 23 "process_geojson", 24 "places", 25 "buildings", 26 "objects", 27 "utils", 28 "resources", 29]
def
process_place( props: dict, confidence: float = 0.0, region_tag: str = 'addr:state', unmatched: Literal['error', 'force', 'ignore'] = 'ignore') -> Dict[str, str]:
10def process_place( 11 props: dict, 12 confidence: float = 0.0, 13 region_tag: str = "addr:state", 14 unmatched: Literal["error", "force", "ignore"] = "ignore", 15) -> Dict[str, str]: 16 """Convert Overture's places properties to OSM tags. 17 18 Example usage: 19 ```python 20 import json 21 from overturetoosm import process_place 22 23 with open("overture.geojson", "r", encoding="utf-8") as f: 24 contents: dict = json.load(f) 25 26 for feature in contents["features"]: 27 feature["properties"] = process_place(feature["properties"], confidence=0.5) 28 29 with open("overture_out.geojson", "w+", encoding="utf-8") as x: 30 json.dump(contents, x, indent=4) 31 ``` 32 Args: 33 props (dict): The feature properties from the Overture GeoJSON. 34 region_tag (str, optional): What tag to convert Overture's `region` tag to. 35 Defaults to `addr:state`. 36 confidence (float, optional): The minimum confidence level. Defaults to 0.0. 37 unmatched (Literal["error", "force", "ignore"], optional): How to handle 38 unmatched Overture categories. The "error" option raises an UnmatchedError 39 exception, "force" puts the category into the `type` key, and "ignore" 40 only returns other properties. Defaults to "ignore". 41 42 Returns: 43 dict[str, str]: The reshaped and converted properties in OSM's flat str:str schema. 44 45 Raises: 46 `overturetoosm.objects.UnmatchedError`: Raised if `unmatched` is set to `error` and 47 the Overture category has no OSM definition. 48 `overturetoosm.objects.ConfidenceError`: Raised if the confidence level is set 49 above a feature's confidence. 50 """ 51 new_props = {} 52 prop_obj = PlaceProps(**props) 53 if prop_obj.confidence < confidence: 54 raise ConfidenceError(confidence, prop_obj.confidence) 55 56 if prop_obj.categories: 57 prim = places_tags.get(prop_obj.categories.main) 58 if prim: 59 new_props = {**new_props, **prim} 60 elif unmatched == "force": 61 new_props["type"] = prop_obj.categories.main 62 elif unmatched == "error": 63 raise UnmatchedError(prop_obj.categories.main) 64 65 if prop_obj.names.primary: 66 new_props["name"] = prop_obj.names.primary 67 68 if prop_obj.phones is not None: 69 new_props["phone"] = prop_obj.phones[0] 70 71 if prop_obj.websites is not None: 72 new_props["website"] = prop_obj.websites[0] 73 74 if add := prop_obj.addresses[0]: 75 if add.freeform: 76 new_props["addr:street_address"] = add.freeform 77 if add.country: 78 new_props["addr:country"] = add.country 79 if add.postcode: 80 new_props["addr:postcode"] = add.postcode 81 if add.locality: 82 new_props["addr:city"] = add.locality 83 if add.region: 84 new_props[region_tag] = add.region 85 86 if prop_obj.sources: 87 new_props["source"] = ( 88 ", ".join({i.dataset for i in prop_obj.sources}) + " via overturetoosm" 89 ) 90 91 if prop_obj.socials is not None: 92 for social in prop_obj.socials: 93 if "facebook" in social: 94 new_props["contact:facebook"] = social 95 elif "twitter" in social: 96 new_props["contact:twitter"] = social 97 98 if prop_obj.brand: 99 new_props["brand"] = prop_obj.brand.names.primary 100 new_props["brand:wikidata"] = prop_obj.brand.wikidata 101 102 return new_props
Convert Overture's places properties to OSM tags.
Example usage:
import json
from overturetoosm import process_place
with open("overture.geojson", "r", encoding="utf-8") as f:
contents: dict = json.load(f)
for feature in contents["features"]:
feature["properties"] = process_place(feature["properties"], confidence=0.5)
with open("overture_out.geojson", "w+", encoding="utf-8") as x:
json.dump(contents, x, indent=4)
Arguments:
- props (dict): The feature properties from the Overture GeoJSON.
- region_tag (str, optional): What tag to convert Overture's
region
tag to. Defaults toaddr:state
. - confidence (float, optional): The minimum confidence level. Defaults to 0.0.
- unmatched (Literal["error", "force", "ignore"], optional): How to handle
unmatched Overture categories. The "error" option raises an UnmatchedError
exception, "force" puts the category into the
type
key, and "ignore" only returns other properties. Defaults to "ignore".
Returns:
dict[str, str]: The reshaped and converted properties in OSM's flat str:str schema.
Raises:
overturetoosm.objects.UnmatchedError
: Raised ifunmatched
is set toerror
and the Overture category has no OSM definition.overturetoosm.objects.ConfidenceError
: Raised if the confidence level is set above a feature's confidence.
def
process_building(props: dict, confidence: float = 0.0) -> Dict[str, str]:
9def process_building( 10 props: dict, 11 confidence: float = 0.0, 12) -> Dict[str, str]: 13 """Convert Overture's building properties to OSM tags. 14 15 Args: 16 props (dict): The feature properties from the Overture GeoJSON. 17 confidence (float, optional): The minimum confidence level. Defaults to 0.0. 18 19 Returns: 20 Dict[str, str]: The reshaped and converted properties in OSM's flat str:str schema. 21 22 Raises: 23 `overturetoosm.objects.ConfidenceError`: Raised if the confidence level is set 24 above a feature's confidence. 25 """ 26 new_props = {} 27 prop_obj = BuildingProps(**props) 28 confidences = [source.confidence for source in prop_obj.sources] 29 if any(conf < confidence for conf in confidences): 30 raise ConfidenceError(confidence, max(confidences)) 31 32 new_props["building"] = prop_obj.class_ 33 34 new_props["source"] = source_statement(prop_obj.sources) 35 36 obj_dict = prop_obj.model_dump(exclude_none=True).items() 37 new_props.update( 38 { 39 k.replace("facade", "building") 40 .replace("_", ":") 41 .replace("color", "colour"): v 42 for k, v in obj_dict 43 if k.startswith(("roof", "facade")) 44 } 45 ) 46 new_props.update({k: v for k, v in obj_dict if k.endswith("height")}) 47 48 if prop_obj.is_underground: 49 new_props["location"] = "underground" 50 if prop_obj.num_floors: 51 new_props["building:levels"] = prop_obj.num_floors 52 if prop_obj.num_floors_underground: 53 new_props["building:levels:underground"] = prop_obj.num_floors_underground 54 if prop_obj.min_floor: 55 new_props["building:min_level"] = prop_obj.min_floor 56 return new_props
Convert Overture's building properties to OSM tags.
Arguments:
- props (dict): The feature properties from the Overture GeoJSON.
- confidence (float, optional): The minimum confidence level. Defaults to 0.0.
Returns:
Dict[str, str]: The reshaped and converted properties in OSM's flat str:str schema.
Raises:
overturetoosm.objects.ConfidenceError
: Raised if the confidence level is set above a feature's confidence.
def
process_geojson( geojson: dict, fx: Callable, confidence: float = 0.0, options: Optional[dict] = None) -> dict:
13def process_geojson( 14 geojson: dict, 15 fx: Callable, 16 confidence: float = 0.0, 17 options: Optional[dict] = None, 18) -> dict: 19 """Convert an Overture `place` GeoJSON to one that follows OSM's schema. 20 21 Example usage: 22 ```python 23 import json 24 from overturetoosm.places import process_geojson 25 26 with open("overture.geojson", "r", encoding="utf-8") as f: 27 contents: dict = json.load(f) 28 geojson = process_geojson(contents, fx=process_building) 29 30 with open("overture_out.geojson", "w+", encoding="utf-8") as x: 31 json.dump(geojson, x, indent=4) 32 ``` 33 Args: 34 geojson (dict): The dictionary representation of the Overture GeoJSON. 35 fx (Callable): The function to apply to each feature. 36 confidence (float, optional): The minimum confidence level. Defaults to 0.0. 37 options (dict, optional): Function-specific options to pass as arguments to 38 the `fx` function. 39 40 Returns: 41 dict: The dictionary representation of the GeoJSON that follows OSM's schema. 42 """ 43 options = options or {} 44 new_features = [] 45 for feature in geojson["features"]: 46 try: 47 feature["properties"] = fx(feature["properties"], confidence, **options) 48 new_features.append(feature) 49 except (ConfidenceError, UnmatchedError): 50 pass 51 52 geojson["features"] = new_features 53 return geojson
Convert an Overture place
GeoJSON to one that follows OSM's schema.
Example usage:
import json
from overturetoosm.places import process_geojson
with open("overture.geojson", "r", encoding="utf-8") as f:
contents: dict = json.load(f)
geojson = process_geojson(contents, fx=process_building)
with open("overture_out.geojson", "w+", encoding="utf-8") as x:
json.dump(geojson, x, indent=4)
Arguments:
- geojson (dict): The dictionary representation of the Overture GeoJSON.
- fx (Callable): The function to apply to each feature.
- confidence (float, optional): The minimum confidence level. Defaults to 0.0.
- options (dict, optional): Function-specific options to pass as arguments to
the
fx
function.
Returns:
dict: The dictionary representation of the GeoJSON that follows OSM's schema.