Locations

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

PointLocation

PointLocation

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

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)	required

Example

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.

__doc__ class-attribute

__doc__ = 'A single point location on Earth\'s surface.\n\nRepresents a discrete point with geodetic coordinates (longitude, latitude, altitude).\nCommonly used for ground stations, imaging targets, or tessellated polygon tiles.\n\nArgs:\n    lon (float): Longitude in degrees (-180 to 180)\n    lat (float): Latitude in degrees (-90 to 90)\n    alt (float): Altitude above ellipsoid in meters (default: 0.0)\n\nExample:\n    ```python\n    import brahe as bh\n\n    # Create a ground station in Svalbard\n    svalbard = bh.PointLocation(lon=15.4, lat=78.2, alt=0.0)\n\n    # With identity\n    svalbard = bh.PointLocation(lon=15.4, lat=78.2, alt=0.0) \\\\\n        .with_name("Svalbard Ground Station") \\\\\n        .with_id(1)\n\n    # With custom properties\n    svalbard = bh.PointLocation(lon=15.4, lat=78.2, alt=0.0) \\\\\n        .add_property("country", "Norway") \\\\\n        .add_property("min_elevation_deg", 5.0)\n\n    # Access coordinates as properties\n    lon = svalbard.lon  # Property (always degrees)\n    lat = svalbard.lat  # Property (always degrees)\n    lat_rad = svalbard.latitude(bh.AngleFormat.RADIANS)  # Method for format conversion\n    ```'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

__module__ class-attribute

__module__ = 'brahe._brahe'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

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

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])

__new__ builtin

__new__(*args, **kwargs)

Create and return a new object. See help(type) for accurate signature.

__repr__ method descriptor

__repr__() -> str

Return repr(self).

__str__ method descriptor

__str__() -> str

Return str(self).

add_property method descriptor

add_property(key: str, value) -> PointLocation

Add a custom property (builder pattern).

Parameters:

Name	Type	Description	Default
key	str	Property name	required
value		Property value (must be JSON-serializable)	required

Returns:

Name	Type	Description
PointLocation	PointLocation	Self for chaining

Example

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

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

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

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.

__doc__ class-attribute

__doc__ = 'A polygonal area on Earth\'s surface.\n\nRepresents a closed polygon with multiple vertices.\nCommonly used for areas of interest, no-fly zones, or imaging footprints.\n\nThe polygon is automatically closed if the first and last vertices don\'t match.\n\nArgs:\n    vertices (list[list[float]]): List of [lon, lat, alt] vertices in degrees and meters\n\nRaises:\n    ValueError: If polygon has fewer than 4 vertices or has validation errors\n\nExample:\n    ```python\n    import brahe as bh\n\n    # Define a rectangular area\n    vertices = [\n        [10.0, 50.0, 0.0],  # lon, lat, alt\n        [11.0, 50.0, 0.0],\n        [11.0, 51.0, 0.0],\n        [10.0, 51.0, 0.0],\n        [10.0, 50.0, 0.0],  # Closed (first == last)\n    ]\n    polygon = bh.PolygonLocation(vertices)\n\n    # With identity\n    polygon = bh.PolygonLocation(vertices) \\\\\n        .with_name("AOI-1") \\\\\n        .add_property("region", "Europe")\n    ```'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

__module__ class-attribute

__module__ = 'brahe._brahe'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to 'utf-8'. errors defaults to 'strict'.

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

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], ...]

__new__ builtin

__new__(*args, **kwargs)

Create and return a new object. See help(type) for accurate signature.

__repr__ method descriptor

__repr__() -> str

Return repr(self).

__str__ method descriptor

__str__() -> str

Return str(self).

add_property method descriptor

add_property(key: str, value) -> PolygonLocation

Add a custom property (builder pattern).

Parameters:

Name	Type	Description	Default
key	str	Property name	required
value		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

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