Data¶

Description¶

Module: geocompy.data

The data module provides utility functions and classes for serializing and deserializing data in the serial communication.

Functions¶

parse_string
parse_bool
get_enum
get_enum_parser

Types¶

Angle
Byte
Vector
Coordinate

Definitions¶

class Angle(value: float, unit: 'deg' | 'rad' | 'gon' = 'rad', *, normalize: bool = False, positive: bool = False)[source]¶

Type to represent an angular value.

Angles support typical arithmetic operations.

Notes

An Angle can be instantiated from a number of units, and can be converted to any other unit, but internally it is always represented in radians.

Parameters:

value: float¶: Angular value to represent.
unit: 'deg' | 'rad' | 'gon' = 'rad'¶: Unit of the source value, by default ‘rad’
normalize: bool = False¶: Normalize angle to +/- full angle, by default False
positive: bool = False¶: Normalize angle only to positive, by default False

Raises:

ValueError – If an unknown unit was passed.

classmethod from_dms(value: str) → Angle[source]¶

Parses angle from DMS notation.

Parameters:

value: str¶: DMS angle to parse.

Return type:

Angle

classmethod parse(string: str, unit: 'deg' | 'rad' | 'gon' = 'rad') → Angle[source]¶

Parses string value to float and creates new Angle.

Parameters:

string: str¶: Floating point number to parse.
unit: 'deg' | 'rad' | 'gon' = 'rad'¶: Unit of the value to parse, by default ‘rad’

Return type:

Angle

static deg2rad(angle: float) → float[source]¶: Converts degrees to radians.

static dms2rad(dms: str) → float[source]¶: Converts DDD-MM-SS to radians.

static gon2rad(angle: float) → float[source]¶: Converts gradians to radians.

static rad2deg(angle: float) → float[source]¶: Converts radians to degrees.

static rad2dms(angle: float, precision: int = 0) → str[source]¶: Converts radians to DDD-MM-SS.

static rad2gon(angle: float) → float[source]¶: Converts radians to gradians.

asunit(unit: 'deg' | 'rad' | 'gon' = 'rad') → float[source]¶

Returns the represented angle in the target unit.

Parameters:

unit: 'deg' | 'rad' | 'gon' = 'rad'¶: Target unit, by default ‘rad’

Returns:

Angular value.

Return type:

float

Raises:

ValueError – If an unknown unit was passed

normalized(positive: bool = True) → Self[source]¶

Returns a copy of the angle normalized to full angle.

Parameters:

positive: bool = True¶: Normalize to [0; +2PI] range, by default True

Returns:

New Angle with normalized value.

Return type:

Angle

relative_to(other: SupportsFloat) → Self[source]¶

Returns an angle relative to a reference angle in the [-180;+180] deg range.

The calculated relative angle is positive in the clockwise, and negative in the counter clockwise-direction. Value is always between -180 degrees and +180 degrees.

Parameters:

other: SupportsFloat¶: Reference angle.

Returns:

Relative angle.

Return type:

Angle

to_dms(precision: int = 0) → str[source]¶

Returns the represented angle as a formatted DDD-MM-SS string.

Returns:: Angle in DMS notation.
Return type:: str

class Byte(value: int)[source]¶

Utility type to represent a single byte value.

The main purpose of this class is to help the parsing and formatting of byte values during the handling of serial communication.

Examples

Creating, then “serializing” a Byte:

>>> b = gc.data.Byte(17)
>>> print(b)
'11'

Parsing a Byte from the serialized representation:

>>> value = "'11'"
>>> b = gc.data.Byte.parse(value)

Parameters:

value: int¶: Number to represent.

Raises:

ValueError – If the passed value is outside the [0; 255] range.

classmethod parse(string: str) → Byte[source]¶

Parses Byte from string representation.

Parameters:

string: str¶: Byte value represented as 2 digit hexadecimal string in single quotes (‘).

Return type:

Byte

Examples

>>> value = "'1A'" # value read from serial line
>>> b = gc.data.Byte.parse(value)

class Coordinate(x: float, y: float, z: float)[source]¶

Type to represent a position with 3D cartesian coordinates.

Coordinates support typical arithmetic operations.

Examples

Creating new coordinate and accessing components:

>>> c = gc.data.Coordinate(1, 2, 3)
>>> print(c)
Coordinate(1.0, 2.0, 3.0)
>>> c.x
1.0
>>> c[1]
2.0
>>> x, y, z = c
>>> z
3.0

Parameters:

x: float¶: X component
y: float¶: Y component
z: float¶: Z component

classmethod from_polar(hz: Angle, v: Angle, dist: float) → Self[source]¶

Constructs 3D cartesian coordinate from polar survey coordinates.

Parameters:

hz: Angle¶: Whole circle bearing.
v: Angle¶: Zenith angle.
dist: float¶: Slope distance.

Return type:

Coordinate

to_2d() → Self[source]¶

Returns a copy of the coordinate with the vertical component set to zero.

Returns:: New coordinate with 0 vertical component.
Return type:: Coordinate

to_polar() → tuple[Angle, Angle, float][source]¶

Converts 3D cartesian coordinates to polar survey coordinates.

Returns:: Whole circle bearing, zenith angle and slope distance.
Return type:: tuple

property e : float[source]¶: Easting (alias of x)

property h : float[source]¶: Height (alias of z)

property n : float[source]¶: Northing (alias of y)

class Vector(x: float, y: float, z: float)[source]¶

Type to represent a position or direction with 3D cartesian coordinates.

Vectors support typical arithmetic operations.

Examples

Creating new vector and accessing components:

>>> c = gc.data.Vector(1, 2, 3)
>>> print(c)
Vector(1.0, 2.0, 3.0)
>>> c.x
1.0
>>> c[1]
2.0
>>> x, y, z = c
>>> z
3.0

Parameters:

x: float¶: X component
y: float¶: Y component
z: float¶: Z component

cross(other: Vector) → Self[source]¶

Calculate the cross product of 2 vectors.

Parameters:

other: Vector¶: Second operand.

Return type:

Self

Raises:

TypeError – If other operand was not compatible.

dot(other: Vector) → float[source]¶

Calculate the dot product of 2 vectors.

Parameters:

other: Vector¶: Second operand.

Return type:

float

Raises:

TypeError – If other operand was not compatible.

length() → float[source]¶

Calculates the length of the vector.

Returns:: Length of the vector.
Return type:: float

normalized() → Self[source]¶

Returns a copy of the vector, normalized to unit length.

Returns:: Normalized vector.
Return type:: Self

swizzle(x: 'x' | 'y' | 'z' | '0', y: 'x' | 'y' | 'z' | '0', z: 'x' | 'y' | 'z' | '0', *, flip_x: bool = False, flip_y: bool = False, flip_z: bool = False) → Self[source]¶

Returns a copy of the vector, with the components rearranged according to the swizzle spec.

Parameters:

x: 'x' | 'y' | 'z' | '0'¶: Component to use as X component.
y: 'x' | 'y' | 'z' | '0'¶: Component to use as Y component.
z: 'x' | 'y' | 'z' | '0'¶: Component to use as Z component.
flip_x: bool = False¶: Negate X component, by default False
flip_y: bool = False¶: Negate Y component, by default False
flip_z: bool = False¶: Negate Z component, by default False

Returns:

Vector with swizzled components.

Return type:

Self

Example

>>> v = Vector(1.0, 2.0, 3.0)
>>> v.swizzle('y', 'x', 'z')
Vector(2.0, 1.0, 3.0)
>>> v.swizzle('x', 'y', '0', flip_x=True)
Vector(-1.0, 2.0, 0.0)

get_enum(e: type[_E], value: _E | str) → _E[source]¶

Returns the member of an Enum with the given name.

If the passed value is already a member instance, the function returns it without modification.

Parameters:

e: type[_E]¶: Enum type to search for member.
value: _E | str¶: The member or the name of the member to return.

Returns:

Enum member instance.

Return type:

Enum

Examples

>>> from enum import Enum
>>>
>>> class MyEnum(Enum):
...     ONE = 1
...     TWO = 2
>>>
>>> gc.data.toenum(MyEnum, 'ONE')
<MyEnum.ONE: 1>
>>> gc.data.toenum(MyEnum, MyEnum.TWO)
<MyEnum.TWO: 2>

get_enum_parser(e: type[_E]) → Callable[[str], _E][source]¶

Returns a parser function that can parse the target enum from the serialized enum value.

Parameters:

e: type[_E]¶: Target enum type.

Returns:

Parser function, that takes a string as input, and returns an enum member.

Return type:

Callable

Examples

>>> from enum import Enum
>>>
>>> class MyEnum(Enum):
...     ONE = 1
...     TWO = 2
>>>
>>> parser = gc.data.enumparser(MyEnum)
>>> parser('1')
<MyEnum.ONE: 1>

parse_bool(value: str) → bool[source]¶

Utility function to parse a serialized boolean value.

Parameters:

value: str¶: Serialized value.

Returns:

Parsed boolean.

Return type:

bool

parse_string(value: str) → str[source]¶

Returns a string value with the enclosing quote marks ("...") removed.

Parameters:

value: str¶: A string value read from the communication with an instrument.

Returns:

String suitable for further processing.

Return type:

str

Notes

When a string value is read from an instrument connection, the string is enclosed quotes to indicated the data type. This is a simple convenience function to strip them.