Qualitative Spatial Reasoning – sc2qsr.spatial.qualitative

sc2qsr.spatial.qualitative.boundary_distance(i: int, elv: float, n: int) → float[source]

Calculates the distance of the boundaries to an elevated origin point

Parameters

  • i (int) – index of the boundary of interest

  • elv (float) – elevation of the point

  • n (int) – distance granularity

Raises

ValueError – if i is not even, it means it is not a boundary, but a sector, which is bounded by boundaries i - 1 and i + 1

Returns

Distance of boundary i to the origin point

Return type

float

sc2qsr.spatial.qualitative.condensed_to_square(k: int, n: int) → tuple[source]

Given the index k of an element in a condensed vector, returns its (x, y) coordinates in a corresponding square matrix. This function always returns coordinates from the lower triagular matrix (x > y).

Parameters

  • k (int) – Index of desired element in the condensed matrix

  • n (int) – dimension of the original square matrix

Returns

tuple (x, y) containing coordinates of element in a square matrix

Return type

tuple

sc2qsr.spatial.qualitative.epra2cart(qdir: int, qdist: int, m: int, n: int, elevation: float = None, clockwise: bool = False) → tuple[source]

Returns an approximate cartesian position for a qualitative sector of direction and distance

Parameters

  • qdir (int) – qualitative direction

  • qdist (int) – qualitative distance

  • m (int) – qualitative direction granularity parameter

  • n (int) – qualitative distance granularity parameter

  • elevation (float, optional) – elevation of the point, defaults to None

  • clockwise (bool, optional) – whether to generate coordinates in a clockwise fashion, defaults to False

Returns

a tuple containing x, y coordinates

Return type

tuple

sc2qsr.spatial.qualitative.epra2pol(qdir: int, qdist: int, m: int, n: int, elevation: float = None, clockwise: bool = False) → tuple[source]

Returns approximate polar coordinates for a qualitative sector of direction and distance

Parameters

  • qdir (int) – qualitative direction

  • qdist (int) – qualitative distance

  • m (int) – qualitative direction granularity parameter

  • n (int) – qualitative distance granularity parameter

  • elevation (float, optional) – elevation of the point, defaults to None

  • clockwise (bool, optional) – whether to generate coordinates in a clockwise fashion, defaults to False

Returns

a tuple containing (rho, phi), that is, distance and angle

Return type

tuple

sc2qsr.spatial.qualitative.equals_absolute_direction(qdv1: numpy.ndarray, qdv2: numpy.ndarray, m: int) → bool[source]

Checks if two condensed qualitative direction vectors are equivalent. This is done by normalizing both vectors and checking if they are equal afterwards.

Parameters

  • qdv1 (numpy.ndarray) – first condensed qualitative direction vector

  • qdv2 (numpy.ndarray) – secondcondensed qualitative direction vector

  • m (int) – qualitative direction granularity parameter

Returns

True if qdv1 and qdv2 are equivalent, else False

Return type

bool

sc2qsr.spatial.qualitative.generate_qualitative_directions(entities: numpy.ndarray, m: int) → numpy.ndarray[source]

Creates a condensed vector of qualitative spatial relations of direction between entities

Parameters

  • entities (numpy.ndarray) – an n x 2 array, where n is the number of entities and the columns represent the (x, y) doordinates of each entity

  • m (int) – granularity parameter, m >= 2

Returns

a condensed vector of qualitative spatial directions between all entities

Return type

numpy.ndarray

Tip

Take a look at sc2qsr.spatial.qualitative.square_to_condensed() for how to convert \((x, y)\) coordinates into an ordinary square matrix into an index \(k\), where the direction of element \(y\) w.r.t. element \(x\) is stored in the condensed vector.

sc2qsr.spatial.qualitative.inverse(i: int, m: int) → int[source]

Calculates the inverse of a relation on a \(STAR_m\) calculus

Parameters

  • i (int) – a relation

  • m (int) – granularity of the STAR calculus

Returns

the inverse of i

Return type

int

sc2qsr.spatial.qualitative.normalize_direction(qdir_vector: numpy.ndarray, m: int) → numpy.ndarray[source]

Normalize a condensed qualitative direction vector so that the relative position between all entities does not affect its final representation. This is done by rotating all relations until the first relation in the vector equals 0.

Parameters

  • qdir_vector (numpy.ndarray) – condensed qualitative direction vector

  • m (int) – qualitative direction granularity parameter, >= 2

Returns

a normalized version of qdir_vector

Return type

numpy.ndarray

sc2qsr.spatial.qualitative.qdir_squareform(qdir_vector: list, m: int) → numpy.ndarray[source]

Converts a vector-form qualitative direction vector to a square-form qualitative direction matrix.

Parameters

  • qdir_vector (list) – condensed qualitative direction vector

  • m (int) – direction granurality parameter

Raises

ValueError – if qdir_vector has the wrong size to be transformed into a square matrix

Returns

square matrix with qualitative directions in one triangular, their inverses in the opposite triangular and the identity in the diagonal

Return type

np.ndarray

sc2qsr.spatial.qualitative.square_to_condensed(x: int, y: int, n: int) → tuple[source]

Returns the index of an element in a condensed vector, given its (x,y) coordinates in a square matrix

Parameters

  • x (int) – x coordinate of element

  • y (int) – y coordinate of element

  • n (int) – dimension of square matrix

Returns

index of an element in the corresponding condensed vector

Return type

int

sc2qsr.spatial.qualitative.to_qdist(d: float, elevation: float, n: int) → int[source]

Converts a quantitative distance to qualitative (boundary or sector)

Parameters

  • d (float) – quantitative distance from the elevated point

  • elevation (float) – elevation of point

  • n (int) – distance granularity

Returns

index of the qualitative distance region at distance d

Return type

int

sc2qsr.spatial.qualitative.to_star(m: int, xa: float, ya: float, xb: float = 0, yb: float = 0, clockwise: bool = False) → int[source]

Calculates the \(STAR_m\) relation of point \(A\) wrt. to point \(B\). In the relation \(A(i)B\),

\[i = \lfloor \frac{\arctan2(y_a - y_b, x_a - x_b) + \pi}{2 \pi} 2m \mod 2m \rfloor\]
Parameters

  • m (int) – granularity of the STAR calculus

  • xa (float) – x-coordinate of point A

  • ya (float) – y-coordinate of point A

  • xb (float) – x-coordinate of point B

  • yb (float) – y-coordinate of point B

  • clockwise (bool, optional) – whether angular sectors are numbered clockwise, defaults to False

Returns

STAR relation of point A wrt. to point B

Return type

int