Feature

The Feature module provides functionality for working with individual geospatial features.

class Feature(layer, srid=3857, data={})[source]

Bases: Base

Parameters:

layer (VectorLayer)
srid (int | None)
data (Dict | None)

BASE_SRID = 3857

__init__(layer, srid=3857, data={})[source]

Constructs all the necessary attributes for the Feature object.

Parameters:

layer (VectorLayer) – The vector layer this feature belongs to
srid (int, optional) – The Spatial Reference System Identifier (default is 3857)
data (Dict, optional) – The feature data contains the feature geometry and properties

Example

>>> from geobox import GeoboxClient, Feature
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> geojson = {
...     "type": "Feature",
...     "geometry": {
...         "type": "Point",
...         "coordinates": [10.0, 10.0]
...     },
...     "properties": {
...         "name": "Test feature"
...     }
... }
>>> feature = Feature(layer=layer, data=geojson, srid=4326) # example srid set to 4326
>>> feature.save()

__dir__()[source]

Return a list of available attributes for the Feature object.

This method extends the default dir() behavior to include: - All keys from the feature data dictionary - All keys from the geometry dictionary - All keys from the properties dictionary

This allows for better IDE autocompletion and introspection of feature attributes.

Returns:: A list of attribute names available on this Feature object.
Return type:: list

__repr__()[source]

Return a string representation of the Feature object.

Returns:: A string representation of the Feature object.
Return type:: str

__getattr__(name)[source]

Get an attribute from the resource.

Parameters:: name (str) – The name of the attribute
Return type:: Any

property srid: int

Get the Spatial Reference System Identifier (SRID) of the feature.

Returns:: The SRID of the feature.
Return type:: int

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> feature = layer.get_feature(id=1)
>>> feature.srid  # 3857

property feature_type: FeatureType

Get the type of the feature.

Returns:: The type of the feature.
Return type:: FeatureType

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> feature = layer.get_feature(id=1)
>>> feature.feature_type

property coordinates: List[float]

Get the coordinates of the ferepoature.

Returns:: The coordinates of the feature.
Return type:: list

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> feature = layer.get_feature(id=1)
>>> feature.coordinates

property length: float

Returns the length of the feature geometry (geometry package extra is required!)

Returns:: the length of the feature geometry
Return type:: float

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> feature = layer.get_feature(id=1)
>>> feature.length

property area: float

Returns the area of thefeature geometry (geometry package extra is required!)

Returns:: the area of thefeature geometry
Return type:: float

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> feature = layer.get_feature(id=1)
>>> feature.area

save()[source]

Save the feature. Creates a new feature if feature_id is None, updates existing feature otherwise.

Returns:: None
Return type:: None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> feature = layer.get_feature(id=1)
>>> feature.properties['name'] = 'New Name'
>>> feature.save()

delete()[source]

Delete the feature.

Returns:: None
Return type:: None

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> feature = layer.get_feature(id=1)
>>> feature.delete()

update(geojson, srid=None)[source]

Update the feature data property.

Parameters:

geojson (Dict) – The GeoJSON data for the feature
srid (int, optional) – the input geometry srid

Returns:

The response from the API.

Return type:

Dict

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> feature = layer.get_feature(id=1)
>>> geojson = {
...     "geometry": {
...         "type": "Point",
...         "coordinates": [10, 20]
...     }
... }
>>> feature.update(geojson)

classmethod create_feature(layer, geojson, srid=3857)[source]

Create a new feature in the vector layer.

Parameters:

layer (VectorLayer) – The vector layer to create the feature in
geojson (Dict) – The GeoJSON data for the feature
srid (int, optional) – the feature srid. default: 3857

Returns:

The created feature instance

Return type:

Feature

Example

>>> from geobox import GeoboxClient
>>> from geobox.feature import Feature
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> geojson = {
...    "type": "Feature",
...    "geometry": {"type": "Point", "coordinates": [10, 20]},
...    "properties": {"name": "My Point"}
... }
>>> feature = Feature.create_feature(layer, geojson)

classmethod get_feature(layer, feature_id, user_id=None)[source]

Get a feature by its ID.

Parameters:

layer (VectorLayer) – The vector layer the feature belongs to
feature_id (int) – The ID of the feature
user_id (int) – specific user. privileges required.

Returns:

The retrieved feature instance

Return type:

Feature

Example

>>> from geobox import GeoboxClient
>>> from geobox.feature import Feature
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> feature = Feature.get_feature(layer, feature_id=1)

property geometry: BaseGeometry

Get the feature geometry as a Shapely geometry object.

Returns:

The Shapely geometry object representing the feature’s geometry

Return type:

shapely.geometry.BaseGeometry

Raises:

ValueError – If the geometry is not a dictionary
ValueError – If the geometry type is not present in the feature data
ValueError – If the geometry coordinates are not present in the feature data
ImportError – If shapely is not installed

Example

>>> from geobox import GeoboxClient
>>> from geobox.feature import Feature
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> feature = layer.get_feature(id=1)
>>> feature.geometry

transform(out_srid)[source]

Transform the feature geometry to a new SRID.

Parameters:

out_srid (int) – The target SRID to transform the geometry to (e.g., 4326 for WGS84, 3857 for Web Mercator)

Returns:

A new Feature instance with transformed geometry.

Return type:

Feature

Raises:

ValueError – If the feature has no geometry or if the transformation fails.
ImportError – If pyproj is not installed.

Example

>>> from geobox import GeoboxClient
>>> from geobox.feature import Feature
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> feature = layer.get_feature(id=1, srid=3857)
>>> # Transform from Web Mercator (3857) to WGS84 (4326)
>>> transformed = feature.transform(out_srid=4326)
>>> transformed.srid  # 4326

_get_other_side_of_relationship(relationship)[source]

Determine which side of a relationship this table is on and return the opposite side.

Used internally to navigate bidirectional relationships.

Parameters:: relationship (Relationship) – The relationship to examine.
Returns:: The endpoint (table or layer) on the opposite side of the relationship from this table.
Return type:: Table | VectorLayer
Raises:: ValueError – If this table is not part of the given relationship.

Note

This method assumes the table is either the source or target, not the relation table in Many-to-Many relationships.

_fetch_related_from_target(target, relationship_uuid)[source]

Fetch related rows/features from a relationship target.

Internal helper that dispatches to the appropriate API method based on target type.

Parameters:

target (Table | VectorLayer) – The target endpoint (Table or VectorLayer) to query.
relationship_uuid (str) – UUID of the relationship to traverse.

Raises:

TypeError – If target is not a Table or VectorLayer.

Returns:

Related rows or features.

Return type:

List[TableRow] | List[Feature]

get_related_records(relationship_uuid)[source]

Get the related records on the other side of the relationship that are linked to this row

Parameters:

relationship_uuid (str) – The uuid of relationship

Returns:

a list of the related records

Return type:

List[TableRow] | List[Feature]

Raises:

ValueError – If the given relationship does not involve the current table (i.e., this row is neither the source nor the target of the relationship).
TypeError – If the relationship target type is not supported for fetching related records.

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> feature = layer.get_feature(feature_id=1)
>>> related_records = feature.get_related_records(relationship_uuid="12345678-1234-5678-1234-567812345678")

associate_with(relationship_uuid, *, target_ids=None, q=None)[source]

Create relationships between the source record and target records

Parameters:

relationship_uuid (str) – the relationship uuid
target_ids (List[int], optional) – a list of target record ids to be associated with the current record
q (str, optional) – query filter on target layer or table to select which target features or rows that are going to be related to the current record

Returns:

the record association result

Return type:

Dict

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> feature = layer.get_feature(feature_id=1)
>>> feature.associate_with(
...     relationship_uuid="12345678-1234-5678-1234-567812345678",
...     target_ids=[1, 2, 3],
... )

disassociate_with(relationship_uuid, *, target_ids=None, q=None)[source]

Remove relationships between the source record and target records

Parameters:

relationship_uuid (str) – the relationship uuid
target_ids (List[int], optional) – a list of target record ids to be disassociated with the current record
q (str, optional) – query filter on target layer or table to select which target features or rows that are going to be related to the current record

Returns:

the record association result

Return type:

Dict

Example

>>> from geobox import GeoboxClient
>>> client = GeoboxClient()
>>> layer = client.get_vector(uuid="12345678-1234-5678-1234-567812345678")
>>> feature = layer.get_feature(feature_id=1)
>>> feature.disassociate_with(
...     relationship_uuid="12345678-1234-5678-1234-567812345678",
...     target_ids=[1, 2, 3],
... )