Camera object

class data_treat.cam.Cam(calib_file=None, picDir=None, firstPic=None, pic_to_cm=None, framerate=None, camRes=None, res=None, cropsize=0, cam_thres=20.0)

Class for the camera object

load_calibration_file(f_name)

Load camera intrinsic, distorsion and transformation matrices from a calibration file

:param f_name:calibration file path

load_from_string(data)

Initialize a camera object from a formatted string such as produced by write_cam_data

Parameters:data – formated string to parse

set_R(R)

Set camera rotation matrix for a given Rodrigues vector

Parameters:R – camera rotation Rodrigues vector

set_R_by_matrix(R)

Set camera rotation matrix for a given matrix

Parameters:R – camera rotation matrix

set_T(T)

Set camera Translation vector

Parameters:T – camera Translation vector

set_crop_size()

Set camera crop size to remove the banner according to the picture effective resolution and the picture target resolution (cam.res)

set_dist(dist)

Set camera distorsion matrix for a given path name (deprecated)

Parameters:dist – camera distorsion matrix file name

set_mask(mask_w, mask_h)

Set black mask to apply on each picture to remove reflexive surfaces

Parameters:mask_h (mask_w,) – mask width and height in pixels

set_mtx(mtx)

Set camera intrinsic matrix for a given path name (deprecated)

Parameters:mtx – camera intrinsic matrix file name

undistort()

Undistort the camera pictures and change the picture file to the undistorted one

write_cam_data()

Writes all camera data into a formated tring

Returns:String containing all relevant camera data

Camera calibration

Finds the top and left cameras intrinsinc and distortion matrices and the rotation/translation matrix between the cameras and the sample.

Most functions were highly inspired from the following source: https://opencv-python-tutroals.readthedocs.io/en/latest/py_tutorials/py_calib3d/py_calibration/py_calibration.html

calibration.main.calibrate_stereo(left_lens, right_lens, left_pos, right_pos, calib_folder, chess_dim, chess_case_len)

Calibrate a stereocamera system given calibration file names

Parameters:

• left_lens,right_lens – path of the right and left camera lens calibration pictures
• left_pos,right_pos – path of the right and left camera position pictures
• calib_folder – calibration result folder
• chess_dim – Number of chess cases -1
• chess_case_len – chess case length

Returns:

nothing but generates the camera calibration files in the “res folder” mtx_top,mtx_left (camera intrinsinc matrix), dist_top,dist_left (passage matrix from the sample to

calibration.main.write_calibration_file(f_name, mtx, dist, R, T)

Write a single camera calibration file

Parameters:

• f_name – calibration file name to save
• mtx – camera intrinsic matrix
• dist – camera distorsion matrix
• R – Rotation between the camera and the sample coordinate system (Rodrigues vector)
• T – Translation vector between the camera and the sample coordinate system

calibration.calib_len.get_cam_matrix(calib_pics, chess_dim, chess_case_len)

Finds the camera intrinsinc and distortion matrices

Parameters:

• calib_pics – calibration chessboard pictures
• chess_dim – Number of chess cases -1
• chess_case_len – chess case length
• pic – default None, picture frame to print in the gui

Returns:

camera intrinsinc and distortion matrices

calibration.find_sample_ori.get_quiver(axis, mtx, mat_pass)

Computes the projection of a vector on a give camera

Parameters:

• axis – vector to project
• mtx – camera intrinsic matrix
• mat_pass – camera transformation matrix

Returns:

calibration.find_sample_ori.get_transfo_mat(calib_pic_file, mtx, dist, chess_dim, chess_case_len, imgpoints=None)

Finds the transformation matrix between the camera’s frame and the sample

Parameters:

• calib_pic_file – picture file of the chessboard
• mtx – camera intrinsinc matrix
• dist – camera distorsion matrix
• chess_dim – Number of cases per chess side minus one
• chess_case_len – real life lenth of the chess square

Returns:

R, T Rotation Rodrigues vector and Translation vector

calibration.find_sample_ori.plot_proj_origin(chessPic, mtx, R, T, chess_dim, chess_case_len)

Plots the chessboard point projection and chessboard coordinate system axis on a camera for visual calibration check

Parameters:

• chessPic – Chessboard picture path
• mtx – camera intrinsic matrix
• R – camera Rotation Rodrigues vector
• T – camera translation vector
• chess_dim – Number of cases per chess side minus one
• chess_case_len – real life lenth of the chess square

Various usefull function for chessboard calibration

calibration.chessboard_tools.change_chess_ori(blobs, objpoints)

Turns the object point array according to the detected blobs position

Parameters:

• blobs – Detected blobs positions
• objpoints – object point array

Returns:

transformed object point array

calibration.chessboard_tools.get_blob_position(img, corners, dim)

Find the grid position of the chessboard circles required to get the chessboard orientation

Parameters:

• img – chessboard picture
• corners – detected corner list
• dim – chessboard dimension

Returns:

blob position in index coordinates

calibration.chessboard_tools.get_chessboard_points(picDir, listPic, criteria, chess_dim)

Finds the chessboard points to use in camera calibration function

Parameters:

• picDir – chessboard picture directory path or single picture name (tif and jpg supported)
• listPic – True if picDir is the path to a list of pictures, False if it is a single picture name
• criteria – Chessboard position CV2 convergence criteria
• pic – default None, picture frame to print in the gui

Returns:

objpoints (checkboard coordinates), imgpoints (picture coordinates), gray (chess gray picture), img, objp, corners2

calibration.chessboard_tools.order_points(pts)

Returns an ordered list of points

Parameters:pts – initial list of points

3D Trajectory reconstruction

functions to reconstruct the object 3D trajectory

data_treat.reconstruction_3d.cam_shift_resize(traj_2d_top, traj_2d_left, cam_top, cam_left)

Gives the 2D screen trajectory in the unresized picture frame

Parameters:

• traj_2d_left (traj_2d_top,) – screen trajectory for the top and left cameras
• cam_top,cam_left – top and left camera objects

Returns:

shift_2d_top, shift_2d_left trajectory list

data_treat.reconstruction_3d.get_3d_coor(minspan_len, traj_2d_left, traj_2d_top, cam_left, cam_top, method='persp', timespan=[])

Retrieve the shot 3D trajectory from each cameras parameters and 2D trajectories

Parameters:

• minspan_len – number of time points
• traj_2d_left – trajectory found by the left camera
• traj_2d_top – trajectory found by the right camera
• cam_top,cam_left – camera object for the top and left camera
• method – “persp” (default) or “persp-opti” - use analytical expression or least square optimisation

Returns:

data_treat.reconstruction_3d.get_3d_nopersp(minspan_len, traj_2d_left, traj_2d_top, cam_left, cam_top)

Find the 3D trajectory of the ball by orthographic projection nor camera exact positions

Parameters:

• minspan_len – number of time points
• traj_2d_left – trajectory found by the left camera
• traj_2d_top – trajectory found by the right camera
• cam_top,cam_left – camera object for the top and left camera

Returns:

X,Y,Z coordinate list

data_treat.reconstruction_3d.get_cam_accuracy(cam, traj_proj, traj_init)

Compute the product of the reprojection error and the camera pixel to cm ratio to estimate a position uncertainty

Parameters:

• cam – Camera object
• traj_proj – 2D reprojected trajectory
• traj_init – 2D detected traj

Returns:

ndarray with the estimated position errors

data_treat.reconstruction_3d.get_proj_coords(X, Y, Z, cam)

Compute the projection of 3D coordinates on a camera screen.

Parameters:

• X,Y,Z – 3D coordinates to be projected
• cam – camera object used for projection

Returns:

data_treat.reconstruction_3d.get_proj_error(var, cam_left, cam_top, pos_2d_left, pos_2d_top)

Compute the projection error between the projection of a guessed 3D coordinate vector and the actual screen point

Parameters:

• var – 3D coordinate triplet
• cam_top,cam_left – camera object for the top and left camera
• pos_2d_left – position found by the left camera
• pos_2d_top – position found by the right camera

Returns:

projection error vector

data_treat.reconstruction_3d.get_proj_list(X, Y, Z, cam)

Computes the projection of a list of points in the 3D space onto the camera

Parameters:

• X,Y,Z – list of 3D coordinates
• cam – cam object

Returns:

two_lists x and y with the camera 2D projected coordinates

data_treat.reconstruction_3d.make_alpha_beta(cam)

Compute necessary coefficients for the 3D coordinate system matrix AX=b for better code readability.

Parameters:cam – camera object

data_treat.reconstruction_3d.make_system_mat(cam_top, cam_left, pos_2d_left, pos_2d_top)

Computes the matrix A, b of the equation system AX = b where X is the shot 3D coordinates

Parameters:

• cam_top,cam_left – camera object for the top and left camera
• pos_2d_left – position found by the left camera
• pos_2d_top – position found by the right camera

Returns:

data_treat.reconstruction_3d.plot_proj_error(traj_top, traj_left, X, Y, Z, cam_top, cam_left, time, savedir='data_treat/Reproj_error.png', plot=True)

Plot the reprojected trajectory for each camera to check for the trajectory errors

Parameters:

• traj_top,traj_left – screen trajectory for the top and left cameras
• X,Y,Z – computed 3D trajectory
• cam_top,cam_left – top and left camera objects
• savedir – path to the directory to save the reprojection error to

data_treat.reconstruction_3d.plot_square(cam, ax)

Plot a square repreentive the cropped camera screen

Parameters:cam – camera object

data_treat.reconstruction_3d.reconstruct_3d(cam_top, cam_left, splitSymb='_', numsplit=1, method='no-persp', plotTraj=True, plot=True, isgui=False, savedir='data_treat/Reproj_error.png')

Reconstruct the 3D trajectory of a moving object filmed by 2 cameras with a given angle between them

Parameters:

• cam_top,cam_left – camera object for the top and left camera
• splitSymb – split symbol used in the images name between name and image number
• numsplit – index corresponding to the image number after the name was split (default 1)
• method – “persp”, “persp-opti” or “no-persp” (default) - using the camera intrinsinc matrix for 3D trajectory or not, using analytical expression or least square optimisation
• plotTraj – Boolean, if True the detected shot position will be plotted
• plot – Boolean, if true the reprojection error will be plotted
• savedir – path to the directory to save the reprojection error to

Returns:

data_treat.reconstruction_3d.shift_cam_coord(timespan, traj_2d_top, traj_2d_left, tau=0.0)

Shifts one of the two cameras of a given time delay to account for asynchronized cameras

Parameters:

• timespan – time vector
• traj_2d_top – 2D pixel trajectory for the top camera
• traj_2d_left – 2D pixel trajectory for the left camera
• tau – time_shift

Returns:

traj_2d_top, traj_2d_left

data_treat.reconstruction_3d.shift_error(tau, X, Y, Z, cam_left, cam_top, traj_left, traj_top, timespan)

Computes the reprojection error obtained by time shifting the left camera of a value of tau

Parameters:

• tau – time shift value
• X,Y,Z – unshifted 3D trajectory
• cam_left,cam_top – cameras objects
• traj_left,traj_top – 2D pixel coordinate trajectory on each camera

:param

data_treat.objectExtract.compute_2d_traj(cam, splitSymb='_', numsplit=-1, plotTraj=True, isgui=False)

Compute the 2D trajectory (in m) of the barycenter of a moving object filmed by a camera, by computing the difference of images with the object and without the object (initial state)

Parameters:

• cam – camera object
• splitSymb – symbol to use to split the picture names (default “_”)
• numsplit – place of the image number in the picture name after splitting (default -1)
• plotTraj – TRue or False, indicate if the detected point should be plotted

Returns:

X,Y trajectory in the camera reference system and the time list

data_treat.objectExtract.filter_val(pic, width, height, tol=20.0)

Compute the barycenter of a point cloud which pixel grey value is above a given threshold

Parameters:

• pic – picture array grey values
• width – picture width
• height – picture height
• tol – filter tolerance (default 20)

Returns:

barycenter x and y coordinates and the number of pixels detected

Trajectory post-processing

Several post processing functions to provide the shot velocity before and after impact, the impact angle and position…

data_treat.data_pp.get_impact_position(X, Y, Z, cam_left, cam_top, plot=True, saveDir='data_treat/', threshold=0.995)

Automatic detection of the moment of impact simply by taking the moment where Y changes direction, within a given threshold

Parameters:

• X,Y,Z – reconstructed X, Y, and Z coordinates (ndarray)
• cam_left,cam_top – left and top camera objects.
• plot – True or False indicate if should plot a verification picture
• saveDir – Directory to save the picture to
• threshold – impact detection threshold

Returns:

impact X,Y,Z position relative to the first detected shot picture position.

data_treat.data_pp.get_init_angle(Xi, Yi, Zi, ti, cam_top, cam_left, plot=True, saveDir='data_treat/', init=0, end=2)

Compute the shot trajectory angle relatively to the shooting axis

Parameters:

• X,Y,Z – reconstructed X, Y, and Z coordinates (ndarray)
• timespan – time point list
• cam_top,cam_left – camera objects
• plot – True or False indicate if should plot a verification picture
• saveDir – Directory to save the picture to
• init,end – initial and final array index used to average the angle value (default: 0 and 2)

data_treat.data_pp.get_velocity(ti, Xi, Yi, Zi, thres=1.3, plot=True, saveDir='data_treat/', init=0, pt_num=2)

Computes the shot velocity before and after the impact by linear fit. Before the impact, the functions continues adding the next acquisition point to the linear fit until the new points reduces the fit success score at less then the previous score * threshold. Then the first point with constant velocity after the impact is searched so that lienar fit with the same number of points as before the impact yields a better score than before the impact. It is based on the assumption that there will always be more acquisition point after the impact than before.

Parameters:

• t – time vector
• Xi,Yi,Zi – 3D coordinates (ndarray)
• thres – threshold for the accepted residual difference (default 1.3)
• plot – True or False indicate if should plot a verification picture
• saveDir – Directory to save the picture to
• init – initial index to compute the initial velocity
• pt_num – minimum number of points to use to compute the velocity

Returns:

VX,VY,VZ initial velocity vector coordinates

data_treat.data_pp.plot_supper(init, end, cam, thres=40.0, ax=None)

Plot the superposition (addition) of a cam shot picture between picture init and end

Parameters:

• init,end – start and stop indices for the addition
• cam – camera object to be used

data_treat.data_pp.pos_screen_resize(x, y, cam)

Returns the coordinate in the resized screen given the coordinates in the usnresized creen (when cropping for higher fps)

Parameters:

• x,y – ndarray containing unresized scree coordinates
• cam – cam object

Returns:

nothing but changes x and y values

data_treat.data_pp.result_plot(X, Y, Z, timespan)

Plot the recovered shot trajectory and velocity

Parameters:

• X,Y,Z – reconstructed X, Y, and Z coordinates (ndarray)
• timespan – time point list

Returns:

nothing

Report generation and save

data_treat.make_report.data_save(traj_3d, cam_top, cam_left)

Save experiment data after 3D trajectory reconstruction

Parameters:

• traj_3d – experiment object to save
• cam_left (cam_top,) – top and left camera object to save

Returns:

1 if success

data_treat.make_report.load_data(fileName, trajectory, cam_top, cam_left)

Load existing data from file

Parameters:

• fileName – name of the file to load
• trajectory – Experiment object to initialize
• cam_left (cam_top,) – top and left camera object to initialize

data_treat.make_report.make_report(traj_3d, cam_top, cam_left, template)

Generates a report of the post-processed values as well as the parameters used to extract the trajectory. Also saves the trajectory.

Parameters:

• traj_3d – Experiment object
• cam_top,cam_left – camera objects used for the trajectory determination
• template – name of the template to use for the report

data_treat.make_report.make_template_file(template, sortie, H, var_names)

Create a file from a given template file

Parameters:

• template – template file name
• sortie – output file name
• H – variable values
• var_names – variable names

GUI fonctions

gui.recons_gui.start_gui()

Setup the main guI window

gui.calibration.calib_tab(root, frame)

Setup teh calibration tab content

Parameters:

• root – tk root window
• frame – calibration tab frame object

Returns:

gui.calibration.launch_calib(entries, numcase, lencase)

Launch calibration procedure

Parameters:

• entries – calibration form entries
• numcase – number of checkboard case form object
• lencase – length of a checkboard case form object

gui.load.load_tab(root, frame, cam_top, cam_left, traj_3d, notebook)

Setup the loading tab

Parameters:

• root – tk root window
• frame – calibration tab frame object
• cam_top,cam_left – top and left camera objects
• traj_3d – Experiment object
• notebook – notebook object the tab belongs to

gui.load.start_load(notebook, f, tra, ct, cl)

loads an analysis by initializing the cameras and experiment objects

Parameters:

• notebook – notebook object the tab belongs to (enables the pp mode)
• f – form entries
• tra – Experiment object
• ct,cl – camera_top and left objects

gui.analysis.ana_tab(root, frame, notebook, cam_top, cam_left, traj_3d)

Setup the analysis tab

Parameters:

• root – root tk window
• frame – frame of the tab to draw in
• notebook – notebook object the tab belongs to
• cam_top,cam_left – top and left camera objects
• traj_3d – Experiment object

gui.analysis.batch_option_active(switch_val, batch_options)

Check if the batch mode was activate and plots the batch options accordingly

Parameters:

• switch_val – batch mode switch
• batch_options – batch option tk Frame

gui.analysis.create_camera(entries, name, cam, pic_to_cm=None)

Create a camera object based on the values filled in the form

Parameters:

• entries – form entries
• name – camera name (top or left)
• cam – camera object
• pic_to_cm – picture to cm ratio if the no-perspective mode is used

Returns:

initialized camera object

gui.analysis.launch_analysis(top_entry, left_entry, notebook, method, cam_top, cam_left, traj_3d, show_traj, ratTop, ratLeft, isbatch, batch_folder, exp_param)

Launch a 3D trajectory analysis

Parameters:

• top_entry,left_entry – form entries for the top and left cameras
• notebook – GUI notebook object (to enable the pp tab at the end
• method – analysis method combobox object
• cam_top,cam_left – camera top and left objects
• traj_3d – Experiment object
• show_traj – Trajectory display checkbox object
• ratTop,ratLeft – pixel to cm ratio form objects for the top and left cameras
• isbatch – checkbox object enabling (or not) batch mode
• batch_folder – batch folder path form object
• exp_param – experimental parameter form object

Returns:

gui.analysis.method_change(val, cam_factors)

Checks if the method was changed to no-perspective and changes the GUI accordingly

Parameters:

• val – method choice tk combobox object
• cam_factors – method parameters to display

gui.analysis.save_pp_params(traj_3d, vels, angles, pos, param_win)

saves PP parameters in an Experiment object and closes the window

Parameters:

• traj_3d – Experiment object
• vels – velocity determination parameters
• angles – angle determination parameters
• pos – impact position determination parameters
• param_win – PP parameter window to shut down

Returns:

gui.analysis.set_cam_mask(root, cam, mask_w, mask_h)

sets the camera mask and closes the mask selection window

gui.analysis.set_mask(cam, form)

Generate the subwindow to set a camera mask

Parameters:

• cam – camera object
• form – camera form values to get the first picture path

gui.analysis.set_pp_params(traj_3d)

Generate the batch PP parameter subwindow

Parameters:traj_3d – Experience object to change

gui.analysis.update_fig(mask, im_act, canvas, ind)

update the mask selection picture as the slider moves

Parameters:

• mask – mask value
• im_act – plotted image ndarray
• canvas – canvas to plot the modified image onto
• ind – 0 for the mask to act on the pictur width, 1 for the picture height

gui.post_processing.launch_pp(vels, cam_top, cam_left, T, traj_3d, fileSave, ang, pos)

Launch a post-processing analysis

Parameters:

• vels – velocity parameter form
• cam_top,cam_left – top and left camera objects
• T – Text canvas to log the results
• traj_3d – Experiment object
• fileSave – report save directory
• ang – angle parameter form
• pos – impact position parameter form

gui.post_processing.move_file(init, end)

Moves a file using either batch or shell command according to the current os (Windows or Linux only)

Parameters:

• init – path of the file to move
• end – target directory path

gui.post_processing.parse_dir(save_dir)

Parses the save directory to get only the directory (without the file name) to save the pictures to

Parameters:save_dir – save directory string Returns:save directory string without the file name

gui.post_processing.pp_tab(root, frame, cam_top, cam_left, traj_3d)

Setup the post-processing tab

Parameters:

• root – tk root window
• frame – calibration tab frame object
• cam_top,cam_left – top and left camera objects
• traj_3d – Experiment object

gui.post_processing.save_res(cam_top, cam_left, T, traj_3d, fileSave)

Saves the results and make a report

Parameters:

• cam_top,cam_left – top and left camera objects
• T – Text canvas to log the results
• traj_3d – Experiment object
• fileSave – report save directory

gui.gui_utils.makeform(root, fields, def_vals, pos='top')

Create a form with several entries. source: https://www.python-course.eu/tkinter_entry_widgets.php

Parameters:

• root – tk Frame object to put the form in
• fields – field name strings (list)
• def_vals – default values string (list)
• pos – tkinter constant position value (tk.TOP, LEFT, RIGHT, BOTTOM)

Returns:

list with each field name (column 0) and entry object (column 1)

gui.gui_utils.plot_fig(figure, size='600x600')

Create a new tk window instance with a figure ploted in a canvas

Parameters:figure – figure to plot Returns:canvas object

gui.gui_utils.popupmsg(msg)

Instantiate a popup with a message and an “ok” button. source: https://pythonprogramming.net/tkinter-popup-message-window/

Parameters:msg – pop-up string message