Base class to predict vowel positions around the face.
The vowel positions are considered targets in the hand trajectory. Currently, 5 vowel positions are possible and they have only one coordinate. For English language, this will have to be changed because some vowels have a movement effect: side-forward, side-down.
Instantiate a vowel position's predictor.
def __init__(self, nb_sights=68):
"""Instantiate a vowel position's predictor.
:param nb_sights: (int) Number of face sights. Must match the one of FaceTwoDim().
:raises: NotImplementedError: given nb sights is not supported.
:raises: sppasTypeError: given nb sights is not of 'int' type.
"""
self._description = MSG_DESCRIPTION_BASE
self.__sights = None
self._f2 = FaceTwoDim()
try:
nb_sights = int(nb_sights)
except ValueError:
raise sppasTypeError(type(nb_sights), 'int')
nb_sights = int(nb_sights)
if nb_sights != self._f2.dim:
raise NotImplementedError('The support for vowel prediction with {:d} sights is not implemented yet. Expected {:d}.'.format(nb_sights, self._f2.dim))
self._vowels = dict()
self.__vowel_mapping = {'b': self._calculate_vowel_b, 'c': self._calculate_vowel_c, 'm': self._calculate_vowel_m, 's': self._calculate_vowel_s, 'sf': self._calculate_vowel_sf, 'sd': self._calculate_vowel_sd, 't': self._calculate_vowel_t, 'n': self._calculate_vowel_n}
Return the list of vowel codes the class can calculate position.
def vowel_codes(self) -> tuple:
"""Return the list of vowel codes the class can calculate position."""
return tuple(self.__vowel_mapping.keys())
Return the number of sights this predictor was trained for.
def get_sights_dim(self) -> int:
"""Return the number of sights this predictor was trained for."""
return self._f2.dim
Set the sights of a face and predict all vowel positions.
If no sights are provided, it uses default sights. It validates the input type and the number of sights before setting them and predicting vowel coordinates.
def set_sights_and_predict_coords(self, sights: sppasSights | None=None, vowels: tuple | None=None) -> None:
"""Set the sights of a face and predict all vowel positions.
If no sights are provided, it uses default sights. It validates the
input type and the number of sights before setting them and predicting
vowel coordinates.
:param sights: (sppasSights | None)
:param vowels: (tuple | None) List of vowel position names. Default is all known ones.
:raises: sppasTypeError: given parameter is not a sppasSights type.
:raises: NotImplementedError: not the expected number of sights
"""
if sights is None:
self.__sights = self._f2.sights
else:
if isinstance(sights, sppasSights) is False:
raise sppasTypeError(type(sights), 'sppasSights')
if len(sights) != self._f2.dim:
raise NotImplementedError('The support for vowel prediction with {:d} sights is not implemented yet. Expected {:d}.'.format(len(sights), self._f2.dim))
self.__sights = sights
if vowels is None:
vowels = self.vowel_codes()
self.predict_vowels_coords(vowels)
Return the absolute position of the given vowel.
Estimated relatively to the sights of a face. Sights must be set before using this method.
def get_vowel_coords(self, vowel: str='n') -> tuple:
"""Return the absolute position of the given vowel.
Estimated relatively to the sights of a face. Sights must be set
before using this method.
:param vowel: (char) Vowel position name. If unknown, 'n' is used instead.
:return: tuple(x, y, r) with point coordinates and radius
:raises: sppasKeyError: Invalid given vowel code.
"""
if vowel in self._vowels:
return self._vowels[vowel]
raise sppasKeyError(vowel, 'Predicted Vowels')
Estimate the absolute position of all the requested vowels.
Estimate the absolute positions of specified vowels relative to the sights of a face. It uses predefined coordinates and calculations to determine these positions and stores them in a dictionary. Sights must be set before using this method.
def predict_vowels_coords(self, vowels: tuple=('n',)) -> None:
"""Estimate the absolute position of all the requested vowels.
Estimate the absolute positions of specified vowels relative to the
sights of a face. It uses predefined coordinates and calculations
to determine these positions and stores them in a dictionary.
Sights must be set before using this method.
:param vowels: (tuple) List of vowel position names. If unknown, 'n' is used instead.
:raises: sppasKeyError: Invalid given vowel code.
"""
self.check(vowels)
self._vowels = dict()
for vowel in vowels:
try:
self._vowels[vowel] = self.__vowel_mapping[vowel]()
except NotImplementedError:
logging.warning(f"No vowel position calculation for vowel '{vowel}'")
pass
Check if the given vowel codes are valid.
def check(self, vowels: tuple):
"""Check if the given vowel codes are valid.
:param vowels: (tuple) The character codes of vowels
:raises: sppasKeyError: Invalid given vowel code.
"""
if self.__sights is None:
logging.warning('Attempting to predict vowel positions but no sights were defined.')
self.set_sights_and_predict_coords()
codes = self.vowel_codes()
for vowel in vowels:
if vowel not in codes:
raise sppasKeyError(vowel, 'Vowel Position Code')
To be overridden. Calculate the position of the neutral position.
def _calculate_vowel_n(self) -> tuple:
"""To be overridden. Calculate the position of the neutral position.
:return: (tuple) coordinates and radius of the neutral position
"""
x = self._x(8)
y = self._y(8) + 4 * (self._y(8) - self._y(57))
return (x, y, 0)
To be overridden. Calculate the position of a cheek bone vowel.
def _calculate_vowel_b(self) -> tuple:
"""To be overridden. Calculate the position of a cheek bone vowel.
:return: (tuple) coordinates and radius of the cheek bone vowel
"""
x = self._x(4) + abs(self._x(36) - self._x(0)) // 2
y = self._y(1) - abs(self._y(1) - self._y(0)) // 3
return (x, y, 0)
To be overridden. Calculate the position of a chin vowel.
def _calculate_vowel_c(self) -> tuple:
"""To be overridden. Calculate the position of a chin vowel.
:return: (tuple) coordinates and radius of the chin vowel
"""
x = self._x(8)
y = self._y(8) - abs(self._y(8) - self._y(57)) // 5
return (x, y, 0)
To be overridden. Calculate the position of a mouth vowel.
def _calculate_vowel_m(self) -> tuple:
"""To be overridden. Calculate the position of a mouth vowel.
:return: (tuple) coordinates and radius of the mouth vowel
"""
x = self._x(48) - abs(self._x(48) - self._x(4)) // 4
y = self._y(60)
return (x, y, 0)
To be overridden. Calculate the position of a side vowel.
def _calculate_vowel_s(self) -> tuple:
"""To be overridden. Calculate the position of a side vowel.
:return: (tuple) coordinates and radius of the side vowel
"""
x = self._x(0) - 2 * abs(self._x(8) - self._x(0)) // 3
y = self._y(4) - abs(self._y(4) - self._y(3)) // 2
return (x, y, 0)
To be overridden. Calculate the position of a side-forward vowel.
def _calculate_vowel_sf(self) -> tuple:
"""To be overridden. Calculate the position of a side-forward vowel.
:return: (tuple) coordinates and radius of the side-forward vowel
"""
raise NotImplementedError
To be overridden. Calculate the position of a side-down vowel.
def _calculate_vowel_sd(self) -> tuple:
"""To be overridden. Calculate the position of a side-down vowel.
:return: (tuple) coordinates and radius of the side-down vowel
"""
raise NotImplementedError
To be overridden. Calculate the position of a throat vowel.
def _calculate_vowel_t(self) -> tuple:
"""To be overridden. Calculate the position of a throat vowel.
:return: (tuple) coordinates and radius of the throat vowel
"""
x = self._x(8)
y = self._y(8) + int(1.2 * float(abs(self._y(8) - self._y(57))))
return (x, y, 0)
def _x(self, idx) -> int:
return self.__sights.x(idx)
def _y(self, idx) -> int:
return self.__sights.y(idx)
Return the width/height ratio of the face sights.
def _radius_ratio(self) -> float:
"""Return the width/height ratio of the face sights."""
return (float(self._x(16) - self._x(0)) + float(self._y(8) - self._y(27))) / 1.85