Drift

Fichier contenant des fonctions pour le drift.

extract_beads(data: DataFrame, max_distance: float = 1, is_3d: bool = True, *, strict: bool = True, k: int = 4) → DataFrame[source]

Extrait des billes suivies à travers les plans en ne conservant que celles qui ont un match dans tous les plans (du premier au dernier plan présent dans data).

La correspondance entre deux plans consécutifs est réalisée avec une contrainte de distance euclidienne de type “sphère” : \(\sqrt{x^2+y^2+z^2} \leq max_{distance}\)

En cas de multiples candidats, on choisit le plus proche en distance euclidienne. Les conflits (un même point du plan suivant proposé pour plusieurs tracks) sont résolus par un appariement glouton sur les distances croissantes (un point ne peut être assigné qu’à un seul track).

Parameters:

data (DataFrame) – DataFrame contenant au minimum les colonnes Plane, X, Y et Z. Chaque ligne représente une détection (un point) dans un plan donné.
max_distance (float) – Distance maximale autorisée entre deux plans (en unités des coordonnées) selon la norme L∞.
is_3d (bool) – Si True, utilise (X,Y,Z). Sinon, utilise uniquement (X,Y).
strict (bool) – Si True, la distance doit être strictement inférieure à la distance maximale (comportement par défaut).
k (int) – Nombre de matchs maximum pour chaques points, permet de gérer les collisions de suivis (par défaut 4 maximum). Dans la réalité, avec des données et paramètres cohérents, il n’y aura qu’un seul match ou aucun pour chaques points.

Returns:

Un nouveau DataFrame ne contenant que les points appartenant à des billes valides, avec une colonne Bead (1..N) indiquant l’identifiant de la bille. Les lignes sont triées par Bead puis Plane.

Raises:

ValueError – Si des colonnes requises sont manquantes, ou si max_distance n’est pas strictement positif.

Return type:

DataFrame

remove_beads(data: DataFrame, beads: DataFrame, decimals: int = 5) → DataFrame[source]

Mets à jour data en lui enlevant les billes identifiées (matching exact sur Plane/X/Y/Z).

Parameters:

data (DataFrame) – Données de localisation (doit contenir Plane, X, Y, Z).
beads (DataFrame) – Billes à retirer (doit contenir Plane, X, Y, Z).
decimals (int) – Nombre de décimales conservées pour la comparaison (évite les problèmes d’arrondi float).

Returns:

Copie de data sans les lignes correspondant aux billes.

Return type:

DataFrame

get_drift(beads: DataFrame, is_3d: bool = True) → DataFrame[source]

Calcule le drift moyen interplans à partir d’un DataFrame de billes suivies.

Le drift est calculé pour chaque bille comme la différence entre deux plans consécutifs :

\(\Delta X(n) = X(n) - X(n-1)\)
\(\Delta Y(n) = Y(n) - Y(n-1)\)
\(\Delta Z(n) = Z(n) - Z(n-1)\) (si is_3d=True)

Et il est associé au plan n (donc le drift commence au plan 2).

Ensuite, on moyenne ces drifts entre toutes les billes disponibles.

Parameters:

beads (DataFrame) – DataFrame contenant au minimum Bead, Plane, X, Y, Z. Chaque bille doit avoir exactement une ligne par plan et les plans doivent être consécutifs.
is_3d (bool) – Si True, calcule aussi le drift en Z. Sinon, la colonne Z est renvoyée à 0.

Returns:

DataFrame avec colonnes Plane, X, Y, Z contenant le drift moyen, pour les plans de 2 à N.

Raises:

ValueError – Si des colonnes sont manquantes, ou incohérence de plans au sein des billes.

Return type:

DataFrame

apply_drift(data: DataFrame, drift: DataFrame, is_3d: bool = True) → DataFrame[source]

Applique une correction de drift à un DataFrame de points.

Le DataFrame drift doit contenir une ligne par plan, avec les colonnes Plane, X, Y et Z. Le drift est supposé défini pour les plans 2..N et associé au plan courant (même convention que get_drift()).

La correction appliquée est :

\(X_{corr}(n) = X(n) - X_{drift}(n)\)
\(Y_{corr}(n) = Y(n) - Y_{drift}(n)\)
\(Z_{corr}(n) = Z(n) - Z_{drift}(n)\)

Parameters:

data (DataFrame) – DataFrame contenant au minimum Plane, X, Y Z.
drift (DataFrame) – DataFrame contenant au minimum Plane, X, Y Z, typiquement pour les plans 2..N.
is_3d (bool) – Si True, applique aussi la correction en Z.

Returns:

Un nouveau DataFrame corrigé (mêmes colonnes que data).

Raises:

ValueError – Si colonnes manquantes dans data ou drift.

Return type:

DataFrame

drift_correction(data: DataFrame, max_distance: float = 1, is_3d: bool = True, *, strict: bool = True, k: int = 4) → tuple[DataFrame, DataFrame][source]

Trouve des billes au sein d’un jeu de donnée, calcule le drift et le corrige.

Parameters:

data (DataFrame) – DataFrame contenant au minimum les colonnes Plane, X, Y et Z. Chaque ligne représente une détection (un point) dans un plan donné.
max_distance (float) – Distance maximale autorisée entre deux plans (en unités des coordonnées) selon la norme L∞.
is_3d (bool) – Si True, utilise (X,Y,Z). Sinon, utilise uniquement (X,Y).
strict (bool) – Si True, la distance doit être strictement inférieure à la distance maximale (comportement par défaut).
k (int) – Nombre de matchs maximum pour chaques points, permet de gérer les collisions de suivis (par défaut 4 maximum). Dans la réalité, avec des données et paramètres cohérents, il n’y aura qu’un seul match ou aucun pour chaques points.

Returns:

Les billes identifiées et un nouveau DataFrame ne contenant les données corrigées.

Return type:

tuple[DataFrame, DataFrame]