PCALoss

class lightning_pose.losses.losses.PCALoss

Bases: Loss

Penalize predictions that fall outside a low-dimensional subspace.

Attributes Summary

LOSS_NAME_MULTIVIEW
LOSS_NAME_SINGLEVIEW

Methods Summary

__call__(keypoints_pred[, stage])	Compute the PCA loss for a batch of predicted keypoints.
compute_loss(predictions)	Compute per-sample PCA reprojection error.
remove_nans(**kwargs)	No-op for PCALoss; NaN handling is performed inside compute_loss().

Attributes Documentation

LOSS_NAME_MULTIVIEW = 'pca_multiview'

LOSS_NAME_SINGLEVIEW = 'pca_singleview'

Methods Documentation

__call__(keypoints_pred: Tensor, stage: Literal['train', 'val', 'test'] | None = None, **kwargs: Any) → tuple[Float[Tensor, ''], list[dict]]

Compute the PCA loss for a batch of predicted keypoints.

Parameters:

• keypoints_pred – predicted keypoint coordinates.

• stage – training stage for logging.

• **kwargs – ignored extra keyword arguments.

Returns:

Tuple of scalar loss and list of logging dicts.

compute_loss(predictions: Float[Tensor, 'num_samples sample_dim']) → Float[Tensor, 'num_samples _']

Compute per-sample PCA reprojection error.

Parameters:

predictions – predicted keypoint coordinates, shape (num_samples, sample_dim).

Returns:

Reprojection error per sample and keypoint.

remove_nans(**kwargs: Any) → Any

No-op for PCALoss; NaN handling is performed inside compute_loss().

__init__(loss_name: Literal['pca_singleview', 'pca_multiview'], components_to_keep: int | float = 0.95, empirical_epsilon_percentile: float = 99.0, epsilon: float | None = None, empirical_epsilon_multiplier: float = 1.0, mirrored_column_matches: ListConfig | list | None = None, columns_for_singleview_pca: ListConfig | list | None = None, data_module: BaseDataModule | UnlabeledDataModule | None = None, log_weight: float = 0.0, device: str | device = 'cpu', centering_method: Literal['mean', 'median'] | None = None, **kwargs: Any) → None

Initialize PCALoss.

Fits a KeypointPCA object on the training data and uses the resulting low-dimensional subspace to penalize out-of-subspace predictions at training time.

Parameters:

• loss_name – "pca_singleview" penalizes single-camera predictions; "pca_multiview" penalizes predictions that are inconsistent across views.

• components_to_keep – passed to KeypointPCA; see its docstring for details.

• empirical_epsilon_percentile – percentile of the training-data reprojection error used to set epsilon when epsilon is None; in [0, 100].

• epsilon – if not None, use this fixed epsilon value and ignore empirical_epsilon_percentile.

• empirical_epsilon_multiplier – scalar multiplier applied to the empirically computed epsilon before use.

• mirrored_column_matches – required for "pca_multiview"; see KeypointPCA for details.

• columns_for_singleview_pca – subset of keypoint indices to use for singleview PCA; None uses all keypoints.

• data_module – data module used by KeypointPCA to extract training data.

• log_weight – final weight in front of the loss term in the objective function is computed as 1.0 / (2.0 * exp(log_weight)).

• device – device on which PCA parameters are stored and loss is computed.

• centering_method – if not None, subtract the per-frame keypoint centroid before fitting PCA. "mean" uses the arithmetic mean; "median" uses the median.

__new__(**kwargs)