https://sppas.org/

SPPAS 4.16

Module sppas.src.anndata

Class sppasPoint

Description

Localization of a point for any numerical representation.

Represents a point identified by a midpoint value and a radius value.

Generally, time is represented in seconds, as a float value ; frames

are represented by integers like ranks.

In this class, the 3 relations <, = and > take into account a radius

value, that represents the uncertainty of the localization. For a point

x, with a radius value of rx, and a point y with a radius value of ry,

these relations are defined as:

  • x = y iff |x - y| <= rx + ry
  • x < y iff not(x = y) and x < y
  • x > y iff not(x = y) and x > y

Example

1: Strictly equals:

  • x = 1.000, rx=0.
  • y = 1.000, ry=0.
  • x = y is true

  • x = 1.00000000000, rx=0.
  • y = 0.99999999675, ry=0.
  • x = y is false

Example

2: Using the radius:

  • x = 1.0000000000, rx=0.0005
  • y = 1.0000987653, ry=0.0005
  • x = y is true (accepts a margin of 1ms between x and y)

  • x = 1.0000000, rx=0.0005
  • y = 1.0011235, ry=0.0005
  • x = y is false

So... an overlap of the vagueness "area" makes the two points equals:

|------------rx----------X-----ry===rx----Y--------ry------|

Constructor

Create a sppasPoint instance.

Parameters

  • midpoint: (float, int) midpoint value.
  • radius: (float, int) represents the vagueness of the point. Radius must be of the same type as midpoint.
def __init__(self, midpoint, radius=None):
    """Create a sppasPoint instance.

    :param midpoint: (float, int) midpoint value.
    :param radius: (float, int) represents the vagueness of the point.
    Radius must be of the same type as midpoint.

    """
    super(sppasPoint, self).__init__()
    self.__midpoint = 0
    self.__radius = None
    self.set_midpoint(midpoint)
    self.set_radius(radius)

Public functions

set

Set self members from another sppasPoint instance.

Parameters

  • other: (sppasPoint)
def set(self, other):
    """Set self members from another sppasPoint instance.

        :param other: (sppasPoint)

        """
    if isinstance(other, sppasPoint) is False:
        raise AnnDataTypeError(other, 'sppasPoint')
    self.set_midpoint(other.get_midpoint())
    self.set_radius(other.get_radius())
is_point

Override. Return True, because self represents a point.

def is_point(self):
    """Override. Return True, because self represents a point."""
    return True
copy

Return a deep copy of self.

def copy(self):
    """Return a deep copy of self."""
    return sppasPoint(self.__midpoint, self.__radius)
get_midpoint

Return the midpoint value.

def get_midpoint(self):
    """Return the midpoint value."""
    return self.__midpoint
set_midpoint

Set the midpoint value.

In versions < 1.9.8, it was required that midpoint >= 0.

Negative values are now accepted because some annotations are not

properly synchronized and then some of them can be negative.

Parameters

  • midpoint: (float, int) is the new midpoint value.

Raises

AnnDataTypeError

def set_midpoint(self, midpoint):
    """Set the midpoint value.

        In versions < 1.9.8, it was required that midpoint >= 0.
        Negative values are now accepted because some annotations are not
        properly synchronized and then some of them can be negative.

        :param midpoint: (float, int) is the new midpoint value.
        :raise: AnnDataTypeError

        """
    if isinstance(midpoint, (int, float, text_type, binary_type)) is False:
        raise AnnDataTypeError(midpoint, 'float, int')
    if isinstance(midpoint, (int, text_type, binary_type)) is True:
        try:
            self.__midpoint = int(midpoint)
            if self.__midpoint < 0:
                logging.warning('Midpoint is negative: {:d}'.format(midpoint))
            return
        except ValueError:
            pass
    try:
        self.__midpoint = float(midpoint)
    except ValueError:
        raise AnnDataTypeError(midpoint, 'float, int')
    if self.__midpoint < 0.0:
        logging.warning('Midpoint is negative: {:f}'.format(midpoint))
get_radius

Return the radius value (float or None).

def get_radius(self):
    """Return the radius value (float or None)."""
    return self.__radius
set_radius

Fix the radius value, ie. the vagueness of the point.

The midpoint value must be set first.

Parameters

  • radius: (float, int, None) the radius value

Raises

AnnDataTypeError, AnnDataNegValueError

def set_radius(self, radius=None):
    """Fix the radius value, ie. the vagueness of the point.

        The midpoint value must be set first.

        :param radius: (float, int, None) the radius value
        :raise: AnnDataTypeError, AnnDataNegValueError

        """
    if radius is not None:
        if sppasPoint.check_types(self.__midpoint, radius) is False:
            raise AnnDataTypeError(radius, str(type(self.__midpoint)))
        if isinstance(radius, float):
            try:
                radius = float(radius)
                if radius < 0.0:
                    raise AnnDataNegValueError(radius)
            except TypeError:
                raise AnnDataTypeError(radius, 'float')
        elif isinstance(radius, int):
            try:
                radius = int(radius)
                if radius < 0:
                    raise AnnDataNegValueError(radius)
            except TypeError:
                raise AnnDataTypeError(radius, 'int')
        if self.__midpoint < radius:
            radius = self.__midpoint
    self.__radius = radius
shift

Shift the point to a given delay.

Parameters

  • delay: (int, float) delay to shift midpoint

Raises

AnnDataTypeError

def shift(self, delay):
    """Shift the point to a given delay.

        :param delay: (int, float) delay to shift midpoint
        :raise: AnnDataTypeError

        """
    if sppasPoint.check_types(self.__midpoint, delay) is False:
        raise AnnDataTypeError(delay, str(type(self.__midpoint)))
    self.__midpoint += delay
duration

Overrides. Return the duration of the point.

Returns

  • (sppasDuration) Duration and its vagueness.
def duration(self):
    """Overrides. Return the duration of the point.

        :returns: (sppasDuration) Duration and its vagueness.

        """
    if self.__radius is None:
        return sppasDuration(0.0, 0.0)
    return sppasDuration(0.0, 2.0 * self.get_radius())
is_int

Return True if the value of the point is an integer.

def is_int(self):
    """Return True if the value of the point is an integer."""
    return isinstance(self.__midpoint, int)
is_float

Return True if the value of the point is a float.

def is_float(self):
    """Return True if the value of the point is a float."""
    return isinstance(self.__midpoint, float)
check_types

True only if midpoint and radius are both of the same types.

Parameters

  • x: any kind of data
  • y: any kind of data

Returns

  • Boolean
@staticmethod
def check_types(x, y):
    """True only if midpoint and radius are both of the same types.

        :param x: any kind of data
        :param y: any kind of data
        :returns: Boolean

        """
    return isinstance(x, type(y))

Overloads

__format__
def __format__(self, fmt):
    return str(self).__format__(fmt)
__repr__
def __repr__(self):
    if self.__radius is None:
        return 'sppasPoint: {!s:s}'.format(self.__midpoint)
    return 'sppasPoint: {!s:s}, {!s:s}'.format(self.__midpoint, self.__radius)
__str__
def __str__(self):
    if self.__radius is None:
        return '{!s:s}'.format(self.__midpoint)
    return '({!s:s}, {!s:s})'.format(self.__midpoint, self.__radius)
__eq__

Equal is required to use '=='.

Used between 2 sppasPoint instances or

between a sppasPoint and an other object representing time.

This relationship takes into account the radius.

Parameters

  • other: (sppasPoint, float, int) the other point to compare
def __eq__(self, other):
    """Equal is required to use '=='.

        Used between 2 sppasPoint instances or
        between a sppasPoint and an other object representing time.
        This relationship takes into account the radius.

        :param other: (sppasPoint, float, int) the other point to compare

        """
    if isinstance(other, sppasPoint) is True:
        delta = abs(self.__midpoint - other.get_midpoint())
        radius = 0
        if self.__radius is not None:
            radius += self.__radius
        if other.get_radius() is not None:
            radius += other.get_radius()
        return delta <= radius
    if isinstance(other, (int, float)):
        if self.__radius is None:
            return self.__midpoint == other
        delta = abs(self.__midpoint - other)
        radius = self.__radius
        return delta <= radius
    return False
__lt__

LowerThan is required to use '<'.

Used between 2 sppasPoint instances

or between a sppasPoint and an other time object.

Parameters

  • other: (sppasPoint, float, int) the other point to compare
def __lt__(self, other):
    """LowerThan is required to use '<'.

        Used between 2 sppasPoint instances
        or between a sppasPoint and an other time object.

        :param other: (sppasPoint, float, int) the other point to compare

        """
    if isinstance(other, sppasPoint) is True:
        return self != other and self.__midpoint < other.get_midpoint()
    return self != other and self.__midpoint < other
__gt__

GreaterThan is required to use '>'.

Used between 2 sppasPoint instances

or between a sppasPoint and an other time object.

Parameters

  • other: (sppasPoint, float, int) the other point to compare
def __gt__(self, other):
    """GreaterThan is required to use '>'.

        Used between 2 sppasPoint instances
        or between a sppasPoint and an other time object.

        :param other: (sppasPoint, float, int) the other point to compare

        """
    if isinstance(other, sppasPoint) is True:
        return self != other and self.__midpoint > other.get_midpoint()
    return self != other and self.__midpoint > other