ParticleDetection.utils.data_loading

Collection of (mostly deprecated) functions to load stereo camera calibration data and rod position data.

Authors: Adrian Niemann (adrian.niemann@ovgu.de)

Date: 02.11.2022

extract_3d_data(df_data: DataFrame) → ndarray[source]

Extract the 3D data from a rod position DataFrame ready for plotting.

Parameters:

df_data (pd.DataFrame) –

Rod position data, with at least the following columns:

"particle", "frame", "x1", "y1", "z1", "x2", "y2", "z2"

Returns:

np.ndarray – Dimensions: [frame, particle, 3, 2]

extract_cam_params(mat_params: dict) → dict[source]

Load camera calibrations from a direct MATLAB *.json export.

Loads camera calibrations, that have been exported to *.json directly from MATLAB and therefore still adhere to MATLAB’s naming and data convention.These are then transferred to the data(/naming) convention used by this package (OpenCV’s data convention).

Parameters:: mat_params (dict) – A MATLAB camera calibration loaded from a *.json file.
Returns:: dict – Camera calibration matrices and distortion coefficients to be used by this package. Has the keys: "matrix", "distortions"

Notes

Camera matrix correspondences:

OpenCV:             Matlab:
[[fx,  0, cx],       [[fx,  0, 0],
 [ 0, fy, cy],        [ s, fy, 0],
 [ 0,  0,  1]]        [cx, cy, 1]]

OpenCV distortion coefficients:

(k1, k2, p1, p2[, k3[, k4, k5, k6[, s1, s2, s3, s4[, tau_x, tau_y]]]])

-> 4, 5, 8, 12, or 14 elements

fx, fy -> focal lengths
cx, cy -> Principal point
k1, k2[, k3, k4, k5, k6] -> Radial (distortion) coefficients
p1, p2 -> Tangential distortion coefficients
s1, s2, s3, s4 -> prism distortion coefficients
τx, τy -> angular parameters (for image sensor tilts)

see: https://de.mathworks.com/help/vision/ref/cameraintrinsics.html https://docs.opencv.org/4.x/d9/d0c/group__calib3d.html

extract_stereo_params(calibration_params: dict) → dict[source]

Load stereo camera calibrations from a direct MATLAB *.json export.

Loads stereo camera calibrations, that have been exported to *.json directly from MATLAB and therefore still adhere to MATLAB’s naming convention. These are then transferred to the naming convention used by this package (OpenCV’s naming convention).

Parameters:: calibration_params (dict) – A MATLAB stereo camera calibration loaded from a *.json file.
Returns:: dict – Stereo camera calibration matrices to be used by this package. Has the keys: "F", "R", "T", "E"

Notes

Nomenclature correspondences:

OpenCV:             Matlab:
F                   FundamentalMatrix
E                   EssentialMatrix
T                   TranslationOfCamera2
R                   inv(RotationOfCamera2)

Matlab docs: (stereoParameters-rotationOfCamera2)

Rotation of camera 2 relative to camera 1, specified as a 3-by-3 matrix. The rotationOfCamera2 and the translationOfCamera2 represent the relative rotation and translation between camera 1 and camera 2, respectively. They convert camera 2 coordinates back to camera 1 coordinates using:

orientation1 = rotationOfCamera2 * orientation2
location1 = translationOfCamera2 * orientation2 + location2

where, orientation1 and location1 represent the absolute pose of camera 1, and orientation2 and ``location2 represent the absolute pose of camera 2.

OpenCV docs:

stereoCalibrate():

R
Output rotation matrix. Together with the translation vector T, this matrix brings points given in the first camera’s coordinate system to points in the second camera’s coordinate system. In more technical terms, the tuple of R and T performs a change of basis from the first camera’s coordinate system to the second camera’s coordinate system. Due to its duality, this tuple is equivalent to the position of the first camera with respect to the second camera coordinate system.

T
Output translation vector, see description above.
stereoRectify():

R
Rotation matrix from the coordinate system of the first camera to the second camera, see stereoCalibrate.

T
Translation vector from the coordinate system of the first camera to the second camera, see stereoCalibrate.

If one computes the poses of an object relative to the first camera and to the second camera, (R1, T1) and (R2, T2), respectively, for a stereo camera where the relative position and orientation between the two cameras are fixed, then those poses definitely relate to each other. This means, if the relative position and orientation (R, T) of the two cameras is known, it is possible to compute (R2, T2) when (R1, T1) is given. This is what the described function does. It computes (R, T) such that:

R2=R * R1
T2=R * T1 + T.

Therefore, one can compute the coordinate representation of a 3D point for the second camera’s coordinate system when given the point’s coordinate representation in the first camera’s coordinate system:

⎡X2⎤            ⎡X1⎤
⎢Y2⎥ = ⎡R T⎤ *  ⎢Y1⎥
⎢Z2⎥   ⎣0 1⎦    ⎢Z1⎥
⎣ 1⎦            ⎣ 1⎦.

See https://de.mathworks.com/help/vision/ref/stereoparameters.html and https://docs.opencv.org/4.x/d9/d0c/group__calib3d.html for more info.

load_calib_from_json(file_name: str) → Tuple[dict, dict] | Tuple[None, dict] | None[source]

Attempts to load camera calibrations or transformations to world/experiment coordinates saved in the MATLAB format.

Parameters:

filename (str)

Returns:

None | dict | tuple
.. warning:: –

Deprecated since version 0.4.0: Please convert your old configurations compatible with load_world_transformation() and load_camera_calibration().

load_camera_calibration(file_name: str) → dict[source]

Loads camera calibration data from *.json files.

Loads calibration data from a stereo camera calibration, in the format given in ./calibration_data.

Parameters:: file_name (str) – Path to the *.json file containing the calibration data.
Returns:: dict – Loaded calibration data.

load_positions_from_txt(base_file_name: str, columns: List[str], frames: Iterable[int], expected_particles: int | None = None) → DataFrame[source]: Loads the rod data from point matching and adds a frame column.

load_world_transformation(file_name: str) → dict[source]

Loads a transformation to world/experiment coordinates from *.json files.

It attempts to load a transformation from camera 1 coordinates to world/experiment coordinates. There are two structures this function can load and distinguish between.

a legacy version leading to a structure:

loaded["transformations"]["M_rotate_x"]
                         ["M_rotate_y"]
                         ["M_rotate_z"]
                         ["M_trans2"]
                         ["M_trans]

a new version that only has one rotation matrix and one translation vector:
```
loaded["rotation"]
      ["translation"]
```

The first structure is then transformed into the second one.

Parameters:

file_name (str) – Path to the *.json file containing the transformation data.

Returns:

dict –

Loaded transformation data in the format:

loaded["rotation"] = ndarray((3, 3))
      ["translation"] = ndarray((3,))

read_image(img_path: Path) → Tensor[source]

Loads an image for detection with an exported model.

Parameters:: img_path (Path)
Returns:: Tensor