Measures¶

For what each measure calculates, see the measures catalog.

dynaface.measures ¶

The registry of Dynaface's measures.

all_measures ¶

all_measures() -> List[MeasureBase]

Return a new instance of every Dynaface measure, in the order they run.

Returns:

Type	Description
`List[MeasureBase]`	List[MeasureBase]: One instance of each measure, all enabled.

dynaface.measures_base ¶

Measurement plugin base classes.

Contract for measures (mirrored by dynaface-lib-dotnet's FaceMeasureBase):

calc() always returns every declared output, whether or not its item is enabled and whether or not render is True. A value that can't be determined is NaN, or None when the measure couldn't run at all.
An item's enabled flag only controls drawing. Choosing which outputs to show or export is the caller's job: AnalyzeFace.get_all_items() lists the enabled outputs, which is what the desktop app uses for its chart and CSV columns.
An item marked display_only (such as AnalyzeLateral's tip_proj) is a drawing switch, not an output: calc() never returns it and get_all_items() never lists it.

MeasureItem ¶

MeasureItem(
    name: str,
    enabled: bool = True,
    display_only: bool = False,
)

Represents an individual measurement item with a name and enabled state.

Initialize a MeasureItem.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the measurement.	required
`enabled`	`bool`	Whether the item is drawn (and, for callers that honor it, shown or exported).	`True`
`display_only`	`bool`	True for a drawing switch that has no value of its own; it is never returned or listed as an output.	`False`

str ¶

__str__() -> str

Return a string representation of the MeasureItem.

Returns:

Name	Type	Description
`str`	`str`	String representation.

MeasureBase ¶

MeasureBase()

Base class for measurement analysis objects.

Initialize the MeasureBase with default settings.

update_for_type ¶

update_for_type(lateral: bool) -> None

Update the enabled state of each measurement item based on view type.

Parameters:

Name	Type	Description	Default
`lateral`	`bool`	True if the measurement is lateral, False if frontal.	required

set_item_enabled ¶

set_item_enabled(name: str, enabled: bool) -> None

Set the enabled state for a specific measurement item by name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the measurement item.	required
`enabled`	`bool`	True to enable, False to disable.	required

is_enabled ¶

is_enabled(name: str) -> bool

Check if a specific measurement item is enabled.

Parameters:

Name	Type	Description	Default
`name`	`str`	The name of the measurement item.	required

Returns:

Name	Type	Description
`bool`	`bool`	True if the item is enabled, False otherwise.

set_enabled ¶

set_enabled(enabled: bool) -> None

Enable or disable the MeasureBase derived class and its items.

Parameters:

Name	Type	Description	Default
`enabled`	`bool`	True to enable, False to disable.	required

sync_items ¶

sync_items() -> None

Synchronize each measurement item with the base class view settings.

select_outputs ¶

select_outputs(
    data: Dict[str, Any], items: List[MeasureItem]
) -> Dict[str, Any]

Return a measure's outputs: every declared item that isn't display-only, whether or not it is enabled, with None for any the measure didn't compute.

Parameters:

Name	Type	Description	Default
`data`	`Dict[str, Any]`	Values computed by the measure.	required
`items`	`List[MeasureItem]`	The measure's declared items.	required

Returns:

Type	Description
`Dict[str, Any]`	Dict[str, Any]: One entry per non-display-only item.

dynaface.measures_frontal ¶

Measures of a frontal (face-on) view.

AnalyzeFAI ¶

AnalyzeFAI()

Bases: MeasureBase

Facial Asymmetry Index (FAI): how much the distance from each eye's inner corner to the same side's mouth corner differs between the two sides, in millimeters.

Outputs

fai: The absolute difference between the two distances; 0 means the sides match.

Initialize the AnalyzeFAI measurement.

abbrev ¶

abbrev() -> str

Return the abbreviation for the FAI measurement.

Returns:

Name	Type	Description
`str`	`str`	Abbreviation string.

calc ¶

calc(face: Any, render: bool = True) -> Dict[str, Any]

Calculate the Facial Asymmetry Index (FAI).

Parameters:

Name	Type	Description	Default
`face`	`Any`	Face object containing landmarks and measurement methods.	required
`render`	`bool`	Whether to render the measurement visually.	`True`

Returns:

Type	Description
`Dict[str, Any]`	Dict[str, Any]: fai, in millimeters.

AnalyzeOralCommissureExcursion ¶

AnalyzeOralCommissureExcursion()

Bases: MeasureBase

Oral commissure excursion (Oral CE): the distance from each corner of the mouth to the middle of the lower lip, in millimeters.

Outputs

oce.l: From the subject's left corner.
oce.r: From the subject's right corner.

Initialize the AnalyzeOralCommissureExcursion measurement.

abbrev ¶

abbrev() -> str

Return the abbreviation for the Oral Commissure Excursion measurement.

Returns:

Name	Type	Description
`str`	`str`	Abbreviation string.

calc ¶

calc(face: Any, render: bool = True) -> Dict[str, Any]

Calculate the Oral Commissure Excursion measurement.

Parameters:

Name	Type	Description	Default
`face`	`Any`	Face object containing landmarks and measurement methods.	required
`render`	`bool`	Whether to render the measurement visually.	`True`

Returns:

Type	Description
`Dict[str, Any]`	Dict[str, Any]: Filtered measurement results.

AnalyzeBrows ¶

AnalyzeBrows()

Bases: MeasureBase

Brow height: the difference in height between the middles of the two brows, in millimeters, measured along lines parallel to the line between the pupils.

Outputs

brow.d: The difference in height.

Initialize the AnalyzeBrows measurement.

abbrev ¶

abbrev() -> str

Return the abbreviation for the brow measurement.

Returns:

Name	Type	Description
`str`	`str`	Abbreviation string.

calc ¶

calc(face: Any, render: bool = True) -> Dict[str, Any]

Calculate the brow distance measurement.

Parameters:

Name	Type	Description	Default
`face`	`Any`	Face object containing landmarks and measurement methods.	required
`render`	`bool`	Whether to render the measurement visually.	`True`

Returns:

Type	Description
`Dict[str, Any]`	Dict[str, Any]: Filtered measurement results.

AnalyzeDentalArea ¶

AnalyzeDentalArea()

Bases: MeasureBase

Dental display: the area of the mouth opening inside the lips, in square millimeters, split at the facial midline.

Outputs

dental_area: The total area.
dental_left: The area of the subject's left half.
dental_right: The area of the subject's right half.
dental_ratio: The smaller half divided by the larger.
dental_diff: The difference between the halves.

Initialize the AnalyzeDentalArea measurement.

abbrev ¶

abbrev() -> str

Return the abbreviation for the dental area measurement.

Returns:

Name	Type	Description
`str`	`str`	Abbreviation string.

calc ¶

calc(face: Any, render: bool = True) -> Dict[str, Any]

Calculate the dental area measurements.

Parameters:

Name	Type	Description	Default
`face`	`Any`	Face object containing landmarks and measurement methods.	required
`render`	`bool`	Whether to render the measurement visually.	`True`

Returns:

Type	Description
`Dict[str, Any]`	Dict[str, Any]: Filtered measurement results.

AnalyzeEyeArea ¶

AnalyzeEyeArea()

Bases: MeasureBase

Eye area: the area of each eye opening (palpebral fissure), in square millimeters.

Outputs

eye.left: The subject's left eye.
eye.right: The subject's right eye.
eye.diff: The difference between them, rounded to 0.01.
eye.ratio: The smaller area divided by the larger.

Initialize the AnalyzeEyeArea measurement.

abbrev ¶

abbrev() -> str

Return the abbreviation for the eye area measurement.

Returns:

Name	Type	Description
`str`	`str`	Abbreviation string.

calc ¶

calc(face: Any, render: bool = True) -> Dict[str, Any]

Calculate the eye area measurements.

Parameters:

Name	Type	Description	Default
`face`	`Any`	Face object containing landmarks and measurement methods.	required
`render`	`bool`	Whether to render the measurement visually.	`True`

Returns:

Type	Description
`Dict[str, Any]`	Dict[str, Any]: Filtered measurement results.

AnalyzePosition ¶

AnalyzePosition()

Bases: MeasureBase

Position: the head's tilt in the image, the distance between the pupils, and the millimeters-per-pixel scale that converts every measurement.

Outputs

tilt: The angle of the line between the pupils, in degrees; 0 when they're level.
pd: The distance between the pupils, in pixels.
px2mm: Millimeters per pixel: AnalyzeFace.pd divided by pd for a frontal face, and 0.24 for a profile.

Initialize the AnalyzePosition measurement.

abbrev ¶

abbrev() -> str

Return the abbreviation for the position measurement.

Returns:

Name	Type	Description
`str`	`str`	Abbreviation string.

calc ¶

calc(face: Any, render: bool = True) -> Dict[str, Any]

Calculate the position measurements (tilt, px2mm, pd).

Parameters:

Name	Type	Description	Default
`face`	`Any`	Face object containing landmarks and measurement methods.	required
`render`	`bool`	Whether to render the measurement visually.	`True`

Returns:

Type	Description
`Dict[str, Any]`	Dict[str, Any]: Filtered measurement results.

AnalyzePose ¶

AnalyzePose()

Bases: MeasureBase

Pose: the head's rotation, in degrees, as estimated by the landmark model.

Outputs

pitch: Nodding up and down, as in saying "yes."
roll: Tilting toward a shoulder.
yaw: Turning left and right, as in saying "no."

Initialize the AnalyzePose measurement.

abbrev ¶

abbrev() -> str

Return the abbreviation for the pose measurements.

Returns:

Name	Type	Description
`str`	`str`	Abbreviation string.

calc ¶

calc(face: Any, render: bool = True) -> Dict[str, Any]

Calculate the pose measurements (pitch, roll, yaw).

Parameters:

Name	Type	Description	Default
`face`	`Any`	Face object containing landmarks and measurement methods.	required
`render`	`bool`	Whether to render the measurement visually.	`True`

Returns:

Type	Description
`Dict[str, Any]`	Dict[str, Any]: Filtered measurement results.

AnalyzeIntercanthalDistance ¶

AnalyzeIntercanthalDistance()

Bases: MeasureBase

Intercanthal distance: the distance between the inner corners of the eyes, in millimeters.

Outputs

id: The distance.

Initializes the measurement with default settings.

abbrev ¶

abbrev() -> str

Returns the abbreviation of the measurement.

Returns:

Name	Type	Description
`str`	`str`	Abbreviation string.

calc ¶

calc(face: Any, render: bool = True) -> Dict[str, float]

Calculates the intercanthal distance (ID) using the landmarks at indices 64 and 68.

Parameters:

Name	Type	Description	Default
`face`	`Any`	A face object containing landmarks.	required
`render`	`bool`	Whether to render the measurement visually.	`True`

Returns:

Type	Description
`Dict[str, float]`	Dict[str, float]: A dictionary containing the intercanthal distance measurement.

AnalyzeMouthLength ¶

AnalyzeMouthLength()

Bases: MeasureBase

Mouth length: the distance between the corners of the mouth, where the lips meet, in millimeters.

Outputs

ml: The distance.

Initializes the measurement with default settings.

abbrev ¶

abbrev() -> str

Returns the abbreviation of the measurement.

Returns:

Name	Type	Description
`str`	`str`	Abbreviation string.

calc ¶

calc(face: Any, render: bool = True) -> Dict[str, float]

Calculates the mouth length (ML) using the landmarks at indices 88 and 92.

Parameters:

Name	Type	Description	Default
`face`	`Any`	A face object containing landmarks.	required
`render`	`bool`	Whether to render the measurement visually.	`True`

Returns:

Type	Description
`Dict[str, float]`	Dict[str, float]: A dictionary containing the mouth length measurement.

AnalyzeNoseFrontal ¶

AnalyzeNoseFrontal()

Bases: MeasureBase

Nose widths seen from the front, in millimeters, between landmarks on the nose's lower outline.

Outputs

nose.alar: The alar width, between the outer edges of the nostrils (WFLW 55 and 59).
nose.nostril: Between the points midway along each nostril (WFLW 56 and 58).

These replace four earlier columns that held only these two widths: nostril was the alar span padded by 20%, dorsal.base the alar span, and nose.tip and dorsal.bridge both the 56-58 span. WFLW has no landmarks on the sides of the nose higher up, so widths along the dorsum can't be measured from landmarks.

Initializes the measurement with default settings.

abbrev ¶

abbrev() -> str

Returns the abbreviation of the measurement.

Returns:

Name	Type	Description
`str`	`str`	Abbreviation string.

calc ¶

calc(face: Any, render: bool = True) -> Dict[str, float]

Calculates the alar and nostril widths.

Parameters:

Name	Type	Description	Default
`face`	`Any`	A face object containing landmarks.	required
`render`	`bool`	Whether to render the measurement visually.	`True`

Returns:

Type	Description
`Dict[str, float]`	Dict[str, float]: nose.alar and nose.nostril in millimeters.

AnalyzeOuterEyeCorners ¶

AnalyzeOuterEyeCorners()

Bases: MeasureBase

Outer eye corners: the distance between the outer corners of the eyes (lateral canthi), in millimeters.

Outputs

oe: The distance.

Initializes the measurement with default settings.

abbrev ¶

abbrev() -> str

Returns the abbreviation of the measurement.

Returns:

Name	Type	Description
`str`	`str`	Abbreviation string.

calc ¶

calc(face: Any, render: bool = True) -> Dict[str, float]

Calculates the outer eye corners distance.

Parameters:

Name	Type	Description	Default
`face`	`Any`	A face object containing landmarks.	required
`render`	`bool`	Whether to render the measurement visually.	`True`

Returns:

Type	Description
`Dict[str, float]`	Dict[str, float]: A dictionary containing the outer eye corners measurement.

AnalyzeLandmarks ¶

AnalyzeLandmarks()

Bases: MeasureBase

Landmarks: the position of each of the 98 landmarks, in pixels, for export.

Outputs

landmark-1-x to landmark-98-y: The x and y of each landmark, numbered from 1, so landmark-1 is face.landmarks[0].

abbrev ¶

abbrev() -> str

Return the abbreviation for the landmarks measure.

Returns:

Name	Type	Description
`str`	`str`	Abbreviation string.

calc ¶

calc(face: Any, render: bool = True) -> Dict[str, Any]

Return the position of all 98 landmarks, drawing them when render is True.

Parameters:

Name	Type	Description	Default
`face`	`Any`	Face object containing landmarks and measurement methods.	required
`render`	`bool`	Whether to render the landmarks visually.	`True`

Returns:

Type	Description
`Dict[str, Any]`	Dict[str, Any]: landmark-1-x, landmark-1-y and so on through landmark-98-y, in pixels, numbered from 1.

dynaface.measures_lateral ¶

Measures of a lateral (side-profile) view.

AnalyzeLateral ¶

AnalyzeLateral()

Bases: MeasureBase

Measures of a side profile, from the landmarks found along its outline.

Outputs

nfa: Nasofrontal angle, in degrees, at the soft tissue nasion between the glabella and the nasal tip.
nla: Nasolabial angle, in degrees, at the subnasal point between the nasal tip and the soft tissue pogonion.
at: Tip projection: the horizontal distance, in pixels, from the nasal tip (A) to point T, which is level with the tip and directly below the nasion.
nt: The vertical distance, in pixels, from the nasion (N) to T.
at_nt: The ratio AT/NT.

The tip_proj item only switches the AT and NT drawing on and off; it has no value of its own.

abbrev ¶

abbrev() -> str

Return the abbreviation for the lateral measures.

Returns:

Name	Type	Description
`str`	`str`	Abbreviation string.

calc ¶

calc(face: Any, render: bool = True) -> Dict[str, float]

Calculate the lateral measures, drawing the enabled ones when render is True.

Parameters:

Name	Type	Description	Default
`face`	`Any`	Face object with its lateral_landmarks set.	required
`render`	`bool`	Whether to render the measurements visually.	`True`

Returns:

Type	Description
`Dict[str, float]`	Dict[str, float]: nfa, nla, at, nt and at_nt, with NaN where a landmark wasn't found, or an empty dict for a face that isn't lateral.

dynaface.measures_skin ¶

The skin tone measure.

AnalyzeSkinTone ¶

AnalyzeSkinTone()

Bases: MeasureBase

Skin tone: the average color of both cheeks, as hue, saturation and brightness.

Outputs

hue: Hue, in degrees from 0 to 360.
sat: Saturation, in percent.
brightness: Brightness, in percent.

abbrev ¶

abbrev() -> str

Return the abbreviation for the skin tone measure.

Returns:

Name	Type	Description
`str`	`str`	Abbreviation string.

draw_swatch ¶

draw_swatch(
    face: Any,
    color_rgb: Any,
    hue_deg: int,
    sat_pct: int,
    bri_pct: int,
) -> None

Draw the average skin color with its HSV values in the top-right corner.

calc ¶

calc(face: Any, render: bool = True) -> Dict[str, Any]

Calculate the skin tone, drawing a swatch of it when render is True.

Parameters:

Name	Type	Description	Default
`face`	`Any`	Face object containing landmarks and measurement methods.	required
`render`	`bool`	Whether to render the swatch visually.	`True`

Returns:

Type	Description
`Dict[str, Any]`	Dict[str, Any]: hue, sat and brightness, or an empty dict when the landmarks it samples are missing.

Measures¶

dynaface.measures ¶

all_measures ¶

dynaface.measures_base ¶

MeasureItem ¶

__str__ ¶

MeasureBase ¶

update_for_type ¶

set_item_enabled ¶

is_enabled ¶

set_enabled ¶

sync_items ¶

select_outputs ¶

dynaface.measures_frontal ¶

AnalyzeFAI ¶

abbrev ¶

calc ¶

AnalyzeOralCommissureExcursion ¶

abbrev ¶

calc ¶

AnalyzeBrows ¶

abbrev ¶

calc ¶

AnalyzeDentalArea ¶

abbrev ¶

calc ¶

AnalyzeEyeArea ¶

abbrev ¶

calc ¶

AnalyzePosition ¶

abbrev ¶

calc ¶

AnalyzePose ¶

abbrev ¶

calc ¶

AnalyzeIntercanthalDistance ¶

abbrev ¶

calc ¶

AnalyzeMouthLength ¶

abbrev ¶

calc ¶

AnalyzeNoseFrontal ¶

abbrev ¶

calc ¶

AnalyzeOuterEyeCorners ¶

abbrev ¶

calc ¶

AnalyzeLandmarks ¶

abbrev ¶

calc ¶

dynaface.measures_lateral ¶

AnalyzeLateral ¶

abbrev ¶

calc ¶

dynaface.measures_skin ¶

AnalyzeSkinTone ¶

abbrev ¶

draw_swatch ¶

calc ¶

str ¶