osm
- Basic Datatypes¶
The osm
submodule contains definitions of the basic data types used
throughout the library.
Native OSM Objects¶
Native OSM object classes are lightwight wrappers around the osmium OSM data classes. They are immutable and generally bound to the lifetime of the buffer they are saved in.
There are five classes representing the basic OSM entities.
-
class
osmium.osm.
OSMObject
¶ This is the base class for all OSM entity classes below and contains all common attributes.
-
changeset
¶ (read-only) Id of changeset where this version of the object was created.
-
deleted
¶ (read-only) True if the object is no longer visible.
-
id
¶ (read-only) OSM id of the object.
-
positive_id
(self: osmium.osm._osm.OSMObject) → int¶ Get the absolute value of the id of this object.
(read-only) List of tags describing the object. See
osmium.osm.TagList
.
-
timestamp
¶ (read-only) Date when this version has been created, returned as a
datetime.datetime
.
-
uid
¶ (read-only) Id of the user that created this version of the object. Only this ID uniquely identifies users.
-
user
¶ (read-only) Name of the user that created this version. Be aware that user names can change, so that the same user ID may appear with different names and vice versa.
-
user_is_anonymous
(self: osmium.osm._osm.OSMObject) → bool¶ Check if the user is anonymous. If true, the uid does not uniquely identify a single user but only the group of all anonymous users in general.
-
version
¶ (read-only) Version number of the object.
-
visible
¶ (read-only) True if the object is visible.
-
-
class
osmium.osm.
Node
¶ Represents a single OSM node. It inherits from OSMObjects and adds a single attribute, the location.
-
location
¶ The geographic coordinates of the node. See
osmium.osm.Location
.
-
replace
(**args)¶ Create a mutable node replacing the properties given in the named parameters. Note that this function only creates a shallow copy which is still bound to the scope of the original object.
-
-
class
osmium.osm.
Way
¶ Represents a OSM way. It inherits the attributes from OSMObjects and adds an ordered list of nodes that describes the way.
-
ends_have_same_id
(self: osmium.osm._osm.Way) → bool¶ True if the start and end node are exactly the same.
-
ends_have_same_location
(self: osmium.osm._osm.Way) → bool¶ True if the start and end node of the way are at the same location.Expects that the coordinates of the way nodes have been loaded (see
osmium.SimpleHandler.apply_buffer()
andosmium.SimpleHandler.apply_file()
). If the locations are not present then the function returns always true.
-
is_closed
(self: osmium.osm._osm.Way) → bool¶ True if the start and end node are the same (synonym for
ends_have_same_id
).
-
nodes
¶ (read-only) Ordered list of nodes. See
osmium.osm.WayNodeList
.
-
replace
(**args)¶ Create a mutable way replacing the properties given in the named parameters. Note that this function only creates a shallow copy which is still bound to the scope of the original object.
-
-
class
osmium.osm.
Relation
¶ Represents a OSM relation. It inherits the attributes from OSMObjects and adds an ordered list of members.
-
members
¶ (read-only) Ordered list of relation members. See
osmium.osm.RelationMemberList
.
-
replace
(**args)¶ Create a mutable relation replacing the properties given in the named parameters. Note that this function only creates a shallow copy which is still bound to the scope of the original object.
-
-
class
osmium.osm.
Area
¶ Areas are a special kind of meta-object representing a polygon. They can either be derived from closed ways or from relations that represent multipolygons. They also inherit the attributes of OSMObjects and in addition contain polygon geometries. Areas have their own unique id space. This is computed as the OSM id times 2 and for relations 1 is added,
-
from_way
(self: osmium.osm._osm.Area) → bool¶ Return true if the area was created from a way, false if it was created from a relation of multipolygon type.
-
inner_rings
(self: osmium.osm._osm.Area, outer_ring: osmium.osm._osm.OuterRing) → osmium.osm._osm.InnerRingIterator¶ Return an iterator over all inner rings of the multipolygon.
-
is_multipolygon
(self: osmium.osm._osm.Area) → bool¶ Return true if this area is a true multipolygon, i.e. it consists of multiple outer rings.
-
num_rings
(self: osmium.osm._osm.Area) → Tuple[int, int]¶ Return a tuple with the number of outer rings and inner rings.
-
orig_id
(self: osmium.osm._osm.Area) → int¶ Compute the original OSM id of this object. Note that this is not necessarily unique because the object might be a way or relation which have an overlapping id space.
-
outer_rings
(self: osmium.osm._osm.Area) → Iterator¶ Return an iterator over all outer rings of the multipolygon.
-
-
class
osmium.osm.
Changeset
¶ A changeset description.
-
bounds
¶ (read-only) The bounding box of the area that was edited.
-
closed_at
¶ (read-only) Timestamp when the changeset was finalized. May be None when the changeset is still open.
-
created_at
¶ (read-only) Timestamp when the changeset was first opened.
-
id
¶ (read-only) Unique ID of the changeset.
-
num_changes
¶ (read-only) The total number of objects changed in this Changeset.
-
open
¶ (read-only) True when the changeset is still open.
(read-only) List of tags describing the changeset. See
osmium.osm.TagList
.
-
uid
¶ (read-only) User ID of the changeset creator.
-
user
¶ (read-only) Name of the user that created the changeset. Be aware that user names can change, so that the same user ID may appear with different names and vice versa.
-
user_is_anonymous
(self: osmium.osm._osm.Changeset) → bool¶ Check if the user anonymous. If true, the uid does not uniquely identify a single user but only the group of all anonymous users in general.
-
Mutable OSM Objects¶
The objects in osmium.osm.mutable
are Python versions of the native OSM
objects that can be modified. You can use these classes as a base class for
your own objects or to modify objects read from a file.
-
class
osmium.osm.mutable.
OSMObject
(base=None, id=None, version=None, visible=None, changeset=None, timestamp=None, uid=None, tags=None, user=None)¶ Mutable version of
osmium.osm.OSMObject
. It exposes the following attributesid
,version
,visible
,changeset
,timestamp
,uid
andtags
. Timestamps may be strings or datetime objects. Tags can be an osmium.osm.TagList, a dict-like object or a list of tuples, where each tuple contains a (key value) string pair.If the
base
parameter is given in the constructor, then the object will be initialised first from the attributes of this base object.
-
class
osmium.osm.mutable.
Node
(base=None, location=None, **attrs)¶ The mutable version of
osmium.osm.Node
. It inherits all attributes from osmium.osm.mutable.OSMObject and adds a location attribute. This may either be an osmium.osm.Location or a tuple of lon/lat coordinates.
-
class
osmium.osm.mutable.
Way
(base=None, nodes=None, **attrs)¶ The mutable version of
osmium.osm.Way
. It inherits all attributes from osmium.osm.mutable.OSMObject and adds a nodes attribute. This may either be andosmium.osm.NodeList
or a list consisting ofosmium.osm.NodeRef
or simple node ids.
-
class
osmium.osm.mutable.
Relation
(base=None, members=None, **attrs)¶ The mutable version of
osmium.osm.Relation
. It inherits all attributes from osmium.osm.mutable.OSMObject and adds a members attribute. This may either be anosmium.osm.RelationMemberList
or a list consisting ofosmium.osm.RelationMember
or tuples of (type, id, role). The member type should be a single character ‘n’, ‘w’ or ‘r’.
Node Reference Lists¶
Line geometries in OSM are simply a sequence of nodes. To simplify processing osmium returns such node sequences using a special datatype that contains a reference to the node id and also the location geometry. The latter is only valid if the node locations have been cached by a location handler.
-
class
osmium.osm.
NodeRef
¶ A reference to a OSM node that also caches the nodes location.
-
lat
¶ (read-only) Latitude (y coordinate) as floating point number.
-
location
¶ (read-only) Node coordinates as a
osmium.osm.Location
object.
-
lon
¶ (read-only) Longitude (x coordinate) as floating point number.
-
ref
¶ (read-only) Id of the referenced node.
-
x
¶ (read-only) X coordinate (longitude) as a fixed-point integer.
-
y
¶ (read-only) Y coordinate (latitude) as a fixed-point integer.
-
-
class
osmium.osm.
NodeRefList
¶ A list of node references, implemented as an immutable sequence of
osmium.osm.NodeRef
. This class is normally not used directly, use one of its subclasses instead.-
ends_have_same_id
(self: osmium.osm._osm.NodeRefList) → bool¶ True if the start and end node are exactly the same.
-
ends_have_same_location
(self: osmium.osm._osm.NodeRefList) → bool¶ True if the start and end node of the way are at the same location. Expects that the coordinates of the way nodes have been loaded (see
osmium.SimpleHandler.apply_buffer()
andosmium.SimpleHandler.apply_file()
). If the locations are not present then the function returns always true.
-
is_closed
(self: osmium.osm._osm.NodeRefList) → bool¶ True if the start and end node are the same (synonym for
ends_have_same_id
).
-
-
class
osmium.osm.
WayNodeList
¶ List of nodes in a way. For its members see
osmium.osm.NodeRefList
.
-
class
osmium.osm.
OuterRing
¶ List of nodes in an outer ring. For its members see
osmium.osm.NodeRefList
.
-
class
osmium.osm.
InnerRing
¶ List of nodes in an inner ring. For its members see
osmium.osm.NodeRefList
.
Other OSM Entity Attributes¶
Some of the attributes of the OSM entities are represented with more complex classes.
-
class
osmium.osm.
Box
¶ A bounding box around a geographic area. It is defined by an
osmium.osm.Location
for the bottem-left corner and anosmium.osm.Location
for the top-right corner. Those locations may be invalid in which case the box is considered invalid, too.-
bottom_left
¶ (read-only) Bottom-left corner of the bounding box.
-
contains
(self: osmium.osm._osm.Box, location: osmium.osm._osm.Location) → bool¶ Check if the given location is inside the box.
-
extend
(*args, **kwargs)¶ Overloaded function.
- extend(self: osmium.osm._osm.Box, location: osmium.osm._osm.Location) -> osmium.osm._osm.Box
Extend the box to include the given location. If the location is invalid the box remains unchanged. If the box is invalid, it will contain only the location after the operation.
- extend(self: osmium.osm._osm.Box, box: osmium.osm._osm.Box) -> osmium.osm._osm.Box
Extend the box to include the given box. If the box to be added is invalid the input box remains unchanged. If the input box is invalid, it will become equal to the box that was added.
-
size
(self: osmium.osm._osm.Box) → float¶ Return the size in square degrees.
-
top_right
¶ (read-only) Top-right corner of the bounding box.
-
valid
(self: osmium.osm._osm.Box) → bool¶ Check if the box coordinates are defined and with the usual bounds.
-
-
class
osmium.osm.
Location
¶ A geographic coordinate in WGS84 projection. A location doesn’t necessarily have to be valid.
-
lat
¶ (read-only) Latitude (y coordinate) as floating point number.Raises an
osmium.InvalidLocationError
when the location is invalid.
-
lat_without_check
(self: osmium.osm._osm.Location) → float¶ Return latitude (y coordinate) without checking if the location is valid.
-
lon
¶ (read-only) Longitude (x coordinate) as floating point number.Raises an
osmium.InvalidLocationError
when the location is invalid.
-
lon_without_check
(self: osmium.osm._osm.Location) → float¶ Return longitude (x coordinate) without checking if the location is valid.
-
valid
(self: osmium.osm._osm.Location) → bool¶ Check that the location is a valid WGS84 coordinate, i.e. that it is within the usual bounds.
-
x
¶ (read-only) X coordinate (longitude) as a fixed-point integer.
-
y
¶ (read-only) Y coordinate (latitude) as a fixed-point integer.
-
-
class
osmium.osm.
RelationMember
¶ Member of a relation.
-
ref
¶ OSM ID of the object. Only unique within the type.
-
role
¶ The role of the member within the relation, a free-text string. If no role is set then the string is empty.
-
type
¶ Type of object referenced, a node, way or relation.
-
-
class
osmium.osm.
RelationMemberList
¶ An immutable sequence of relation members
osmium.osm.RelationMember
.
-
class
osmium.osm.
TagList
¶ A fixed list of tags. The list is exported as an unmutable, dictionary-like object where the keys are tag strings and the items are
osmium.osm.Tag
.-
get
(*args, **kwargs)¶ Overloaded function.
- get(self: osmium.osm._osm.TagList, key: str, default: str) -> str
- get(self: osmium.osm._osm.TagList, arg0: str) -> str
-