Skip to content

Locations

Location types represent ground positions or areas that satellites can access.

PointLocation

PointLocation 

PointLocation(lon: float, lat: float, alt: float = 0.0)

A single point location on Earth's surface.

Represents a discrete point with geodetic coordinates (longitude, latitude, altitude). Commonly used for ground stations, imaging targets, or tessellated polygon tiles.

Parameters:

Name Type Description Default
lon float

Longitude in degrees (-180 to 180)

 required
lat float

Latitude in degrees (-90 to 90)

 required
alt float

Altitude above ellipsoid in meters (default: 0.0)

 0.0
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import brahe as bh

# Create a ground station in Svalbard
svalbard = bh.PointLocation(lon=15.4, lat=78.2, alt=0.0)

# With identity
svalbard = bh.PointLocation(lon=15.4, lat=78.2, alt=0.0) \\
    .with_name("Svalbard Ground Station") \\
    .with_id(1)

# With custom properties
svalbard = bh.PointLocation(lon=15.4, lat=78.2, alt=0.0) \\
    .add_property("country", "Norway") \\
    .add_property("min_elevation_deg", 5.0)

# Access coordinates as properties
lon = svalbard.lon  # Property (always degrees)
lat = svalbard.lat  # Property (always degrees)
lat_rad = svalbard.latitude(bh.AngleFormat.RADIANS)  # Method for format conversion

Initialize instance.

alt property 

alt: float

Get altitude in meters.

Returns:

Name Type Description
float float

Altitude in meters

lat property 

lat: float

Get latitude in degrees.

Returns:

Name Type Description
float float

Latitude in degrees

lon property 

lon: float

Get longitude in degrees.

Returns:

Name Type Description
float float

Longitude in degrees

properties property 

properties: PropertiesDict

Get custom properties dictionary.

Returns:

Name Type Description
PropertiesDict PropertiesDict

Dictionary-like wrapper for properties that supports assignment
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
import brahe as bh

loc = bh.PointLocation(15.4, 78.2, 0.0)

# Dict-style assignment
loc.properties["climate"] = "Arctic"
loc.properties["country"] = "Norway"

# Dict-style access
print(loc.properties["climate"])  # "Arctic"

# Dict methods
if "country" in loc.properties:
    del loc.properties["country"]

# Iteration
for key in loc.properties.keys():
    print(key, loc.properties[key])

_get_properties_dict method descriptor 

_get_properties_dict()

Internal method: Get properties as a plain Python dict.

_remove_property method descriptor 

_remove_property(key)

Internal method: Remove a property.

_set_property method descriptor 

_set_property(key, json_str)

Internal method: Set a property value.

add_property method descriptor 

add_property(key: str, value: Any) -> PointLocation

Add a custom property (builder pattern).

Parameters:

Name Type Description Default
key str

Property name

 required
value Any

Property value (must be JSON-serializable)

 required

Returns:

Name Type Description
PointLocation PointLocation

Self for chaining
Example 
1
2
3
4
5
import brahe as bh

location = bh.PointLocation(lon=15.4, lat=78.2, alt=0.0) \\
    .add_property("country", "Norway") \\
    .add_property("elevation_mask_deg", 5.0)

altitude method descriptor 

altitude() -> float

Get altitude in meters.

Returns:

Name Type Description
float float

Altitude in meters

center_ecef method descriptor 

center_ecef() -> ndarray

Get center position in ECEF coordinates [x, y, z].

Returns:

Name Type Description
ndarray ndarray

ECEF position in meters [x, y, z]

center_geodetic method descriptor 

center_geodetic() -> ndarray

Get center coordinates in geodetic format [lon, lat, alt].

Returns:

Name Type Description
ndarray ndarray

Geodetic coordinates [longitude_deg, latitude_deg, altitude_m]

from_geojson builtin 

from_geojson(geojson: dict) -> PointLocation

Create from GeoJSON Point Feature.

Parameters:

Name Type Description Default
geojson dict

GeoJSON Feature object with Point geometry

 required

Returns:

Name Type Description
PointLocation PointLocation

New location instance

Raises:

Type Description
ValueError

If GeoJSON is invalid or not a Point Feature
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
import brahe as bh

geojson = {
    "type": "Feature",
    "geometry": {
        "type": "Point",
        "coordinates": [15.4, 78.2, 0.0]
    },
    "properties": {
        "name": "Svalbard"
    }
}

location = bh.PointLocation.from_geojson(geojson)

generate_uuid method descriptor 

generate_uuid() -> Any

Generate a new UUID (mutating).

get_id method descriptor 

get_id() -> int

Get the numeric ID.

Returns:

Type Description
int

int | None: ID if set, None otherwise

get_name method descriptor 

get_name() -> str

Get the name.

Returns:

Type Description
str

str | None: Name if set, None otherwise

get_uuid method descriptor 

get_uuid() -> str

Get the UUID as a string.

Returns:

Type Description
str

str | None: UUID string if set, None otherwise

latitude method descriptor 

latitude(angle_format: AngleFormat) -> float

Get latitude with angle format conversion.

Parameters:

Name Type Description Default
angle_format AngleFormat

Desired output format (DEGREES or RADIANS)

 required

Returns:

Name Type Description
float float

Latitude in specified format

longitude method descriptor 

longitude(angle_format: AngleFormat) -> float

Get longitude with angle format conversion.

Parameters:

Name Type Description Default
angle_format AngleFormat

Desired output format (DEGREES or RADIANS)

 required

Returns:

Name Type Description
float float

Longitude in specified format

set_id method descriptor 

set_id(id: int | None) -> Any

Set the numeric ID (mutating).

Parameters:

Name Type Description Default
id int | None

ID to set, or None to clear

 required

set_name method descriptor 

set_name(name: str | None) -> Any

Set the name (mutating).

Parameters:

Name Type Description Default
name str | None

Name to set, or None to clear

 required

to_geojson method descriptor 

to_geojson() -> dict

Export to GeoJSON Feature format.

Returns:

Name Type Description
dict dict

GeoJSON Feature object
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
import brahe as bh

location = bh.PointLocation(lon=15.4, lat=78.2, alt=0.0) \\
    .with_name("Svalbard")

geojson = location.to_geojson()
# Returns:
# {
#     "type": "Feature",
#     "geometry": {
#         "type": "Point",
#         "coordinates": [15.4, 78.2, 0.0]
#     },
#     "properties": {
#         "name": "Svalbard"
#     }
# }

with_id method descriptor 

with_id(id: int) -> PointLocation

Set the numeric ID (builder pattern).

Parameters:

Name Type Description Default
id int

Numeric identifier

 required

Returns:

Name Type Description
PointLocation PointLocation

Self for chaining

with_name method descriptor 

with_name(name: str) -> PointLocation

Set the name (builder pattern).

Parameters:

Name Type Description Default
name str

Human-readable name

 required

Returns:

Name Type Description
PointLocation PointLocation

Self for chaining

with_new_uuid method descriptor 

with_new_uuid() -> PointLocation

Generate a new UUID (builder pattern).

Returns:

Name Type Description
PointLocation PointLocation

Self for chaining

with_uuid method descriptor 

with_uuid(uuid_str: str) -> PointLocation

Set the UUID from a string (builder pattern).

Parameters:

Name Type Description Default
uuid_str str

UUID string

 required

Returns:

Name Type Description
PointLocation PointLocation

Self for chaining

Raises:

Type Description
ValueError

If UUID string is invalid

PolygonLocation

PolygonLocation 

PolygonLocation(vertices: list[list[float]])

A polygonal area on Earth's surface.

Represents a closed polygon with multiple vertices. Commonly used for areas of interest, no-fly zones, or imaging footprints.

The polygon is automatically closed if the first and last vertices don't match.

Parameters:

Name Type Description Default
vertices list[list[float]]

List of [lon, lat, alt] vertices in degrees and meters

 required

Raises:

Type Description
ValueError

If polygon has fewer than 4 vertices or has validation errors
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import brahe as bh

# Define a rectangular area
vertices = [
    [10.0, 50.0, 0.0],  # lon, lat, alt
    [11.0, 50.0, 0.0],
    [11.0, 51.0, 0.0],
    [10.0, 51.0, 0.0],
    [10.0, 50.0, 0.0],  # Closed (first == last)
]
polygon = bh.PolygonLocation(vertices)

# With identity
polygon = bh.PolygonLocation(vertices) \\
    .with_name("AOI-1") \\
    .add_property("region", "Europe")

Initialize instance.

alt property 

alt: float

Get center altitude in meters.

Returns:

Name Type Description
float float

Center altitude in meters

lat property 

lat: float

Get center latitude in degrees.

Returns:

Name Type Description
float float

Center latitude in degrees

lon property 

lon: float

Get center longitude in degrees.

Returns:

Name Type Description
float float

Center longitude in degrees

num_vertices property 

num_vertices: int

Get number of unique vertices (excluding closure).

Returns:

Name Type Description
int int

Number of unique vertices

properties property 

properties: PropertiesDict

Get custom properties dictionary.

Returns:

Name Type Description
PropertiesDict PropertiesDict

Dictionary-like wrapper for properties that supports assignment
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
import brahe as bh

verts = [[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [1.0, 1.0, 0.0], [0.0, 1.0, 0.0]]
poly = bh.PolygonLocation(verts)

# Dict-style assignment
poly.properties["region"] = "Test Area"
poly.properties["area_km2"] = 123.45

# Dict-style access
print(poly.properties["region"])  # "Test Area"

# Dict methods
if "area_km2" in poly.properties:
    del poly.properties["area_km2"]

vertices property 

vertices: ndarray

Get polygon vertices.

Returns all vertices including the closure vertex (first == last).

Returns:

Name Type Description
ndarray ndarray

Vertices as Nx3 array [[lon, lat, alt], ...]

_get_properties_dict method descriptor 

_get_properties_dict()

Internal method: Get properties as a plain Python dict.

_remove_property method descriptor 

_remove_property(key)

Internal method: Remove a property.

_set_property method descriptor 

_set_property(key, json_str)

Internal method: Set a property value.

add_property method descriptor 

add_property(key: str, value: Any) -> PolygonLocation

Add a custom property (builder pattern).

Parameters:

Name Type Description Default
key str

Property name

 required
value Any

Property value (must be JSON-serializable)

 required

Returns:

Name Type Description
PolygonLocation PolygonLocation

Self for chaining

altitude method descriptor 

altitude() -> float

Get center altitude in meters.

Returns:

Name Type Description
float float

Center altitude in meters

center_ecef method descriptor 

center_ecef() -> ndarray

Get center position in ECEF coordinates [x, y, z].

Returns:

Name Type Description
ndarray ndarray

ECEF position in meters [x, y, z]

center_geodetic method descriptor 

center_geodetic() -> ndarray

Get center coordinates in geodetic format [lon, lat, alt].

Returns:

Name Type Description
ndarray ndarray

Geodetic coordinates [longitude_deg, latitude_deg, altitude_m]

from_geojson builtin 

from_geojson(geojson: dict) -> PolygonLocation

Create from GeoJSON Polygon Feature.

Parameters:

Name Type Description Default
geojson dict

GeoJSON Feature object with Polygon geometry

 required

Returns:

Name Type Description
PolygonLocation PolygonLocation

New polygon instance

Raises:

Type Description
ValueError

If GeoJSON is invalid or not a Polygon Feature
Example 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
import brahe as bh

geojson = {
    "type": "Feature",
    "geometry": {
        "type": "Polygon",
        "coordinates": [[
            [10.0, 50.0, 0.0],
            [11.0, 50.0, 0.0],
            [11.0, 51.0, 0.0],
            [10.0, 51.0, 0.0],
            [10.0, 50.0, 0.0]
        ]]
    },
    "properties": {
        "name": "AOI-1"
    }
}

polygon = bh.PolygonLocation.from_geojson(geojson)

generate_uuid method descriptor 

generate_uuid() -> Any

Generate a new UUID (mutating).

get_id method descriptor 

get_id() -> int

Get the numeric ID.

Returns:

Type Description
int

int | None: ID if set, None otherwise

get_name method descriptor 

get_name() -> str

Get the name.

Returns:

Type Description
str

str | None: Name if set, None otherwise

get_uuid method descriptor 

get_uuid() -> str

Get the UUID as a string.

Returns:

Type Description
str

str | None: UUID string if set, None otherwise

latitude method descriptor 

latitude(angle_format: AngleFormat) -> float

Get center latitude with angle format conversion.

Parameters:

Name Type Description Default
angle_format AngleFormat

Desired output format (DEGREES or RADIANS)

 required

Returns:

Name Type Description
float float

Center latitude in specified format

longitude method descriptor 

longitude(angle_format: AngleFormat) -> float

Get center longitude with angle format conversion.

Parameters:

Name Type Description Default
angle_format AngleFormat

Desired output format (DEGREES or RADIANS)

 required

Returns:

Name Type Description
float float

Center longitude in specified format

set_id method descriptor 

set_id(id: int | None) -> Any

Set the numeric ID (mutating).

Parameters:

Name Type Description Default
id int | None

ID to set, or None to clear

 required

set_name method descriptor 

set_name(name: str | None) -> Any

Set the name (mutating).

Parameters:

Name Type Description Default
name str | None

Name to set, or None to clear

 required

to_geojson method descriptor 

to_geojson() -> dict

Export to GeoJSON Feature format.

Returns:

Name Type Description
dict dict

GeoJSON Feature object

with_id method descriptor 

with_id(id: int) -> PolygonLocation

Set the numeric ID (builder pattern).

Parameters:

Name Type Description Default
id int

Numeric identifier

 required

Returns:

Name Type Description
PolygonLocation PolygonLocation

Self for chaining

with_name method descriptor 

with_name(name: str) -> PolygonLocation

Set the name (builder pattern).

Parameters:

Name Type Description Default
name str

Human-readable name

 required

Returns:

Name Type Description
PolygonLocation PolygonLocation

Self for chaining

with_new_uuid method descriptor 

with_new_uuid() -> PolygonLocation

Generate a new UUID (builder pattern).

Returns:

Name Type Description
PolygonLocation PolygonLocation

Self for chaining

with_uuid method descriptor 

with_uuid(uuid_str: str) -> PolygonLocation

Set the UUID from a string (builder pattern).

Parameters:

Name Type Description Default
uuid_str str

UUID string

 required

Returns:

Name Type Description
PolygonLocation PolygonLocation

Self for chaining

Raises:

Type Description
ValueError

If UUID string is invalid