sports2d 0.8.24__py3-none-any.whl → 0.8.25__py3-none-any.whl

Sports2D/Demo/Config_demo.toml

@@ -97,7 +97,8 @@ tracking_mode = 'sports2d' # 'sports2d' or 'deepsort'. 'deepsort' is slower, har
 keypoint_likelihood_threshold = 0.3 # Keypoints whose likelihood is lower will not be taken into account
 average_likelihood_threshold = 0.5  # Person will be ignored if average likelihood of good keypoints is lower than this value
 keypoint_number_threshold = 0.3     # Person will be ignored if the number of good keypoints (above keypoint_likelihood_threshold) is less than this fraction
-max_distance = 100  # in px or None # If a person is detected further than max_distance from its position on the previous frame, it will be considered as a new one
+max_distance = 250  # in px or None # If a person is detected further than max_distance from its position on the previous frame, it will be considered as a new one
+
 
 [px_to_meters_conversion]
 # Pixel to meters conversion
@@ -105,15 +106,17 @@ to_meters = true
 make_c3d = true
 save_calib = true
 
-# If conversion from first_person_height
-floor_angle = 'auto'    # 'auto' or a value in degrees, eg 2.3. If 'auto', estimated from the line formed by the toes when they are on the ground (where speed = 0)
-xy_origin = ['auto']    # ['auto'] or [px_x,px_y]. N.B.: px_y points downwards. If ['auto'], direction estimated from the start to the end of the line formed by the toes when they are on the ground
+# Compensate for perspective effects, which make the further limb look smaller. 1-2% coordinate error at 10 m, less if the camera is further away
+perspective_value = 10 # Either camera-to-person distance (m), or focal length (px), or field-of-view (degrees or radians), or '' if perspective_unit=='from_calib'
+perspective_unit = 'distance_m' # 'distance_m', 'f_px', 'fov_deg', 'fov_rad', or 'from_calib'
+
+# Compensate for camera horizon 
+floor_angle = 'auto' # float, 'from_kinematics', 'from_calib', or 'auto' # 'auto' is equivalent to 'from_kinematics', ie angle calculated from foot contacts. 'from_calib' calculates it from a toml calibration file. Use float to manually specify it in degrees
+xy_origin = ['auto'] # [px_x,px_y], or ['from kinematics'], ['from_calib'], or ['auto']. # BETWEEN BRACKETS! # ['auto'] is equivalent to ['from_kinematics'], ie origin estimated at first foot contact, direction is direction of motion. ['from_calib'] calculates it from a calibration file. Use [px_x,px_y] to manually specify it in pixels (px_y points downwards)
+
+# Optional calibration file
+calib_file = ''      # Calibration file in the Pose2Sim toml format, or '' if not available
 
-# If conversion from a calibration file
-calib_file = ''         # Calibration in the Pose2Sim format. 'calib_demo.toml', or '' if not available
-# subject_distance
-# focal_distance
-# recalculate_extrinsics
 
 [angles]
 display_angle_values_on = ['body', 'list'] # 'body', 'list', ['body', 'list'], 'none'. Display angle values on the body, as a list in the upper left of the image, both, or do not display them.

Sports2D/Sports2D.py

@@ -152,7 +152,7 @@ DEFAULT_CONFIG =   {'base': {'video_input': ['demo.mp4'],
                                 'keypoint_likelihood_threshold': 0.3,
                                 'average_likelihood_threshold': 0.5,
                                 'keypoint_number_threshold': 0.3,
-                                'max_distance': 100,
+                                'max_distance': 250,
                                 'CUSTOM': { 'name': 'Hip',
                                             'id': 19,
                                             'children': [{'name': 'RHip',
@@ -194,10 +194,12 @@ DEFAULT_CONFIG =   {'base': {'video_input': ['demo.mp4'],
                     'px_to_meters_conversion': {
                                 'to_meters': True,
                                 'make_c3d': True,
-                                'calib_file': '',
+                                'save_calib': True,
+                                'perspective_value': 10.0,
+                                'perspective_unit': 'distance_m',
                                 'floor_angle': 'auto',
                                 'xy_origin': ['auto'],
-                                'save_calib': True
+                                'calib_file': '',
                                 },
                     'angles':   {'display_angle_values_on': ['body', 'list'],
                                 'fontSize': 0.3,
@@ -269,16 +271,21 @@ DEFAULT_CONFIG =   {'base': {'video_input': ['demo.mp4'],
 
 CONFIG_HELP =   {'config': ["C", "path to a toml configuration file"],
                 'video_input': ["i", "webcam, or video_path.mp4, or video1_path.avi video2_path.mp4 ... Beware that images won't be saved if paths contain non ASCII characters"],
+                'time_range': ["t", "start_time end_time. In seconds. Whole video if not specified. start_time1 end_time1 start_time2 end_time2 ... if multiple videos with different time ranges"],
                 'nb_persons_to_detect': ["n", "number of persons to detect. int or 'all'. 'all' if not specified"],
                 'person_ordering_method': ["", "'on_click', 'highest_likelihood', 'largest_size', 'smallest_size', 'greatest_displacement', 'least_displacement', 'first_detected', or 'last_detected'. 'on_click' if not specified"],
                 'first_person_height': ["H", "height of the reference person in meters. 1.65 if not specified. Not used if a calibration file is provided"],
                 'visible_side': ["", "front, back, left, right, auto, or none. 'auto front none' if not specified. If 'auto', will be either left or right depending on the direction of the motion. If 'none', no IK for this person"],
+                'participant_mass': ["", "mass of the participant in kg or none. Defaults to 70 if not provided. No influence on kinematics (motion), only on kinetics (forces)"],
+                'perspective_value': ["", "Either camera-to-person distance (m), or focal length (px), or field-of-view (degrees or radians), or '' if perspective_unit=='from_calib'"],
+                'perspective_unit': ["", "'distance_m', 'f_px', 'fov_deg', 'fov_rad', or 'from_calib'"],
+                'do_ik': ["", "do inverse kinematics. false if not specified"],
+                'use_augmentation': ["", "Use LSTM marker augmentation. false if not specified"],
                 'load_trc_px': ["", "load trc file to avaid running pose estimation again. false if not specified"],
                 'compare': ["", "visually compare motion with trc file. false if not specified"],
-                'webcam_id': ["w", "webcam ID. 0 if not specified"],
-                'time_range': ["t", "start_time end_time. In seconds. Whole video if not specified. start_time1 end_time1 start_time2 end_time2 ... if multiple videos with different time ranges"],
                 'video_dir': ["d", "current directory if not specified"],
                 'result_dir': ["r", "current directory if not specified"],
+                'webcam_id': ["w", "webcam ID. 0 if not specified"],
                 'show_realtime_results': ["R", "show results in real-time. true if not specified"],
                 'display_angle_values_on': ["a", '"body", "list", "body" "list", or "none". body list if not specified'],
                 'show_graphs': ["G", "show plots of raw and processed results. true if not specified"],
@@ -303,11 +310,8 @@ CONFIG_HELP =   {'config': ["C", "path to a toml configuration file"],
                 'xy_origin': ["", "origin of the xy plane. 'auto' if not specified"],
                 'calib_file': ["", "path to calibration file. '' if not specified, eg no calibration file"],
                 'save_calib': ["", "save calibration file. true if not specified"],
-                'do_ik': ["", "do inverse kinematics. false if not specified"],
-                'use_augmentation': ["", "Use LSTM marker augmentation. false if not specified"],
                 'feet_on_floor': ["", "offset marker augmentation results so that feet are at floor level. true if not specified"],
                 'use_simple_model': ["", "IK 10+ times faster, but no muscles or flexible spine, no patella. false if not specified"],
-                'participant_mass': ["", "mass of the participant in kg or none. Defaults to 70 if not provided. No influence on kinematics (motion), only on kinetics (forces)"],
                 'close_to_zero_speed_m': ["","Sum for all keypoints: about 50 px/frame or 0.2 m/frame"], 
                 'tracking_mode': ["", "'sports2d' or 'deepsort'. 'deepsort' is slower, harder to parametrize but can be more robust if correctly tuned"],
                 'deepsort_params': ["", 'Deepsort tracking parameters: """{dictionary between 3 double quotes}""". \n\

Sports2D/Utilities/common.py

@@ -36,6 +36,9 @@ __status__ = "Development"
 
 
 ## CONSTANTS
+# 4 points joint angle: between knee and ankle, and toe and heel. Add 90° offset and multiply by 1
+# 3 points joint angle: between ankle, knee, hip. -180° offset, multiply by -1
+# 2 points segment angle: between horizontal and ankle and knee, 0° offset, multiply by -1
 angle_dict = { # lowercase!
     # joint angles
     'right ankle': [['RKnee', 'RAnkle', 'RBigToe', 'RHeel'], 'dorsiflexion', 90, 1],

Sports2D/Utilities/tests.py

@@ -96,7 +96,7 @@ def test_workflow():
 
     # With no pixels to meters conversion, one person to select, lightweight mode, detection frequency, slowmo factor, gaussian filter, RTMO body pose model
     demo_cmd3 = ["sports2d", "--show_realtime_results", "False", "--show_graphs", "False", "--save_graphs", "False",
-                #  "--calib_file", "calib_demo.toml", 
+                 "--floor_angle", "from_calib", "--xy_origin", "from_calib", "--perspective_unit", "from_calib", "--calib_file", os.path.join(root_dir, "demo_Sports2D", "demo_Sports2D_calib.toml"), 
                  "--nb_persons_to_detect", "1", "--person_ordering_method", "greatest_displacement", 
                  "--mode", "lightweight", "--det_frequency", "50", 
                  "--slowmo_factor", "4",
@@ -104,9 +104,10 @@ def test_workflow():
                  "--pose_model", "body", "--mode", """{'pose_class':'RTMO', 'pose_model':'https://download.openmmlab.com/mmpose/v1/projects/rtmo/onnx_sdk/rtmo-m_16xb16-600e_body7-640x640-39e78cc4_20231211.zip', 'pose_input_size':[640, 640]}"""]
     subprocess.run(demo_cmd3, check=True, capture_output=True, text=True, encoding='utf-8', errors='replace')
     
-    # With a time range, inverse kinematics, marker augmentation
+    # With a time range, inverse kinematics, marker augmentation, perspective value in fov
     demo_cmd4 = ["sports2d", "--person_ordering_method", "greatest_displacement", "--show_realtime_results", "False", "--show_graphs", "False", "--save_graphs", "False",
                  "--time_range", "1.2", "2.7",
+                 "--perspective_value", "40", "--perspective_unit", "fov_deg",
                  "--do_ik", "True", "--use_augmentation", "True", 
                  "--nb_persons_to_detect", "all", "--first_person_height", "1.65",
                  "--visible_side", "auto", "front", "--participant_mass", "55.0", "67.0"]

Sports2D/process.py

@@ -90,6 +90,8 @@ from Pose2Sim.filtering import *
 # Silence numpy "RuntimeWarning: Mean of empty slice"
 import warnings
 warnings.filterwarnings("ignore", category=RuntimeWarning, message="Mean of empty slice")
+warnings.filterwarnings("ignore", category=RuntimeWarning, message="All-NaN slice encountered")
+warnings.filterwarnings("ignore", category=RuntimeWarning, message="invalid value encountered in scalar divide")
 
 # Not safe, but to be used until OpenMMLab/RTMlib's SSL certificates are updated
 import ssl
@@ -1275,7 +1277,7 @@ def select_persons_on_vid(video_file_path, frame_range, all_pose_coords):
     return selected_persons
 
 
-def compute_floor_line(trc_data, score_data, keypoint_names = ['LBigToe', 'RBigToe'], toe_speed_below = 7, score_threshold=0.5):
+def compute_floor_line(trc_data, score_data, keypoint_names = ['LBigToe', 'RBigToe'], toe_speed_below = 7, score_threshold=0.3):
     '''
     Compute the floor line equation, angle, and direction
     from the feet keypoints when they have zero speed.
@@ -1325,7 +1327,7 @@ def compute_floor_line(trc_data, score_data, keypoint_names = ['LBigToe', 'RBigT
 
     # Fit a line to the zero-speed coordinates
     floor_line = np.polyfit(low_speeds_X, low_speeds_Y, 1) # (slope, intercept)
-    angle = -np.arctan(floor_line[0]) # angle of the floor line in degrees
+    angle = -np.arctan(floor_line[0]) # angle of the floor line in radians
     xy_origin = [0, floor_line[1]] # origin of the floor line
 
     # Gait direction
@@ -1334,14 +1336,159 @@ def compute_floor_line(trc_data, score_data, keypoint_names = ['LBigToe', 'RBigT
     return angle, xy_origin, gait_direction
 
 
-def convert_px_to_meters(Q_coords_kpt, first_person_height, height_px, cx, cy, floor_angle, visible_side='none'):
+def get_distance_from_camera(perspective_value=10, perspective_unit='distance_m', calib_file =None, height_px=1, height_m=1, cam_width=1, cam_height=1):
+    '''
+    Compute the distance between the camera and the person based on the chosen perspective unit.
+
+    INPUTS:
+    - perspective_value: Value associated with the chosen perspective unit.
+    - perspective_unit: Unit used to compute the distance. Can be 'distance_m', 'f_px', 'fov_rad', 'fov_deg', or 'from_calib'.
+    - calib_file: Path to the toml calibration file.
+    - height_px: Height of the person in pixels.
+    - height_m: Height of the first person in meters.
+    - cam_width: Width of the camera frame in pixels.
+    - cam_height: Height of the camera frame in pixels.
+    
+    OUTPUTS:
+    - distance_m: Distance between the camera and the person in meters.
+    '''
+
+    if perspective_unit == 'from_calib':
+        if not calib_file:
+            perspective_unit = 'distance_m'
+            distance_m = 10.0
+            logging.warning(f'No calibration file provided. Using a default distance of {distance_m} m between the camera and the person to convert px to meters.')
+        else:
+            calib_params_dict = retrieve_calib_params(calib_file)
+            f_px = calib_params_dict['K'][0][0][0]
+            distance_m = f_px / height_px * height_m
+    elif perspective_unit == 'distance_m':
+        distance_m = perspective_value
+    elif perspective_unit == 'f_px':
+        f_px = perspective_value
+        distance_m = f_px / height_px * height_m
+    elif perspective_unit == 'fov_rad':
+        fov_rad = perspective_value
+        f_px = max(cam_width, cam_height)/2 / np.tan(fov_rad / 2)
+        distance_m = f_px / height_px * height_m
+    elif perspective_unit == 'fov_deg':
+        fov_rad = np.radians(perspective_value)
+        f_px = max(cam_width, cam_height)/2 / np.tan(fov_rad / 2)
+        distance_m = f_px / height_px * height_m
+
+    return distance_m
+
+
+def get_floor_params(floor_angle='auto', xy_origin=['auto'], 
+                     calib_file=None, height_px=1, height_m=1, 
+                     fps=30, trc_data=pd.DataFrame(), score_data=pd.DataFrame(), toe_speed_below=1, score_threshold=0.5, 
+                     cam_width=1, cam_height=1):
+    '''
+    Compute the floor angle and the xy_origin based on calibration file, kinematics, or user input.
+
+    INPUTS:
+    - floor_angle: Method to compute the floor angle. Can be 'auto', 'from_calib', 'from_kinematics', or a numeric value in degrees.
+    - xy_origin: Method to compute the xy_origin. Can be ['auto'], ['from_calib'], ['from_kinematics'], or a list of two numeric values in pixels [cx, cy].
+    - calib_file: Path to a toml calibration file.
+    - height_px: Height of the person in pixels.
+    - height_m: Height of the first person in meters.
+    - fps: Framerate of the video in frames per second. Used if estimating floor line from kinematics.
+    - trc_data: DataFrame containing the pose data in pixels for one person. Used if estimating floor line from kinematics.
+    - score_data: DataFrame containing the keypoint scores for one person. Used if estimating floor line from kinematics.
+    - toe_speed_below: Speed below which the foot is considered to be stationary, in m/s. Used if estimating floor line from kinematics.
+    - score_threshold: Minimum average keypoint score to consider a frame for floor line estimation.
+    - cam_width: Width of the camera frame in pixels. Used if failed to estimate floor line from kinematics.
+    - cam_height: Height of the camera frame in pixels. Used if failed to estimate floor line from kinematics.
+
+    OUTPUTS:
+    - floor_angle_estim: Estimated floor angle in radians.
+    - xy_origin_estim: Estimated xy_origin as a list of two numeric values in pixels [cx, cy].
+    - gait_direction: Estimated gait direction. 'left' if < 0, 'right' otherwise.
+    '''
+    
+    # Estimate floor angle from the calibration file
+    if floor_angle == 'from_calib' or xy_origin == ['from_calib']:
+        if not calib_file:
+            if floor_angle == 'from_calib':
+                floor_angle = 'auto'
+            if  xy_origin == ['from_calib']:
+                xy_origin = ['auto']
+            logging.warning(f'No calibration file provided. Estimating floor angle and xy_origin from the pose of the first selected person.')
+        else:
+            calib_params_dict = retrieve_calib_params(calib_file)
+
+            R90z = np.array([[0.0, -1.0, 0.0],
+                            [1.0, 0.0, 0.0],
+                            [0.0, 0.0, 1.0]])
+            R270x = np.array([[1.0, 0.0, 0.0],
+                            [0.0, 0.0, 1.0],
+                            [0.0, -1.0, 0.0]])
+
+            R_cam = cv2.Rodrigues(calib_params_dict['R'][0])[0]
+            T_cam = np.array(calib_params_dict['T'][0])
+            R_world, T_world = world_to_camera_persp(R_cam, T_cam)
+            Rfloory = R90z.T @ R_world @ R270x.T
+            T_world = R90z.T @ T_world
+            floor_angle_calib = np.arctan2(Rfloory[0,2], Rfloory[0,0])
+            
+            cu = calib_params_dict['K'][0][0][2]
+            cv = calib_params_dict['K'][0][1][2]
+            cx = 0.0
+            cy = cv + T_world[2]* height_px / height_m
+            xy_origin_calib = [cx, cy]
+
+    # Estimate xy_origin from the line formed by the toes when they are on the ground (where speed = 0)
+    px_per_m = height_px/height_m
+    toe_speed_below_px_frame = toe_speed_below * px_per_m / fps # speed below which the foot is considered to be stationary
+    try:
+        if all(key in trc_data for key in ['LBigToe', 'RBigToe']):
+            floor_angle_kin, xy_origin_kin, gait_direction = compute_floor_line(trc_data, score_data, keypoint_names=['LBigToe', 'RBigToe'], toe_speed_below=toe_speed_below_px_frame, score_threshold=score_threshold)
+        else:
+            floor_angle_kin, xy_origin_estim, gait_direction = compute_floor_line(trc_data, score_data, keypoint_names=['LAnkle', 'RAnkle'], toe_speed_below=toe_speed_below_px_frame, score_threshold=score_threshold)
+            xy_origin_kin[1] = xy_origin_kin[1] + 0.13*px_per_m # approx. height of the ankle above the floor
+            logging.warning(f'The RBigToe and LBigToe are missing from your pose estimation model. Using ankles - 13 cm to compute the floor line.')
+    except:
+        floor_angle_kin = 0
+        xy_origin_kin = cam_width/2, cam_height/2
+        logging.warning(f'Could not estimate the floor angle and xy_origin from person {0}. Make sure that the full body is visible. Using floor angle = 0° and xy_origin = [{cam_width/2}, {cam_height/2}] px.')
+
+    # Determine final floor angle estimation
+    if floor_angle == 'from_calib':
+        floor_angle_estim = floor_angle_calib
+    elif floor_angle in ['auto', 'from_kinematics']:
+        floor_angle_estim = floor_angle_kin
+    else:
+        try:
+            floor_angle_estim =  np.radians(float(floor_angle))
+        except:
+            raise ValueError(f'Invalid floor_angle: {floor_angle}. Must be "auto", "from_calib", "from_kinematics", or a numeric value in degrees.')
+
+    # Determine final xy_origin estimation
+    if xy_origin == ['from_calib']:
+        xy_origin_estim = xy_origin_calib
+    elif xy_origin in [['auto'], ['from_kinematics']]:
+        xy_origin_estim = xy_origin_kin
+    else:
+        try:
+            xy_origin_estim = [float(v) for v in xy_origin]
+        except:
+            raise ValueError(f'Invalid xy_origin: {xy_origin}. Must be "auto", "from_calib", "from_kinematics", or a list of two numeric values in pixels.')
+    
+    return floor_angle_estim, xy_origin_estim, gait_direction
+
+
+def convert_px_to_meters(Q_coords_kpt, first_person_height, height_px, distance_m, cam_width, cam_height, cx, cy, floor_angle, visible_side='none'):
     '''
     Convert pixel coordinates to meters.
+    Corrects for floor angle, floor level, and depth perspective errors.
 
     INPUTS:
     - Q_coords_kpt: pd.DataFrame. The xyz coordinates of a keypoint in pixels, with z filled with zeros
     - first_person_height: float. The height of the person in meters
     - height_px: float. The height of the person in pixels
+    - cam_width: float. The width of the camera frame in pixels
+    - cam_height: float. The height of the camera frame in pixels
+    - distance_m: float. The distance between the camera and the person in meters
     - cx, cy: float. The origin of the image in pixels
     - floor_angle: float. The angle of the floor in radians
     - visible_side: str. The side of the person that is visible ('right', 'left', 'front', 'back', 'none')
@@ -1350,19 +1497,36 @@ def convert_px_to_meters(Q_coords_kpt, first_person_height, height_px, cx, cy, f
     - Q_coords_kpt_m: pd.DataFrame. The XYZ coordinates of a keypoint in meters
     '''
 
+    # u,v coordinates
     u = Q_coords_kpt.iloc[:,0]
     v = Q_coords_kpt.iloc[:,1]
+    cu = cam_width / 2
+    cv = cam_height / 2
 
-    X = first_person_height / height_px * ((u-cx) + (v-cy)*np.sin(floor_angle))
-    Y = - first_person_height / height_px * np.cos(floor_angle) * (v-cy - np.tan(floor_angle)*(u-cx))
-
+    # Normative Z coordinates
     marker_name = Q_coords_kpt.columns[0]
     if 'marker_Z_positions' in globals() and visible_side!='none' and marker_name in marker_Z_positions[visible_side].keys():
-        Z = X.copy()
+        Z = u.copy()
         Z[:] = marker_Z_positions[visible_side][marker_name]
     else:
-        Z = np.zeros_like(X)
-
+        Z = np.zeros_like(u)
+
+    ## Compute X and Y coordinates in meters
+    # X =   first_person_height / height_px * (u-cu)
+    # Y = - first_person_height / height_px * (v-cv)
+    ## With floor angle and level correction:
+    # X =   first_person_height / height_px * ((u-cx)*np.cos(floor_angle) + (v-cy)*np.sin(floor_angle))
+    # Y = - first_person_height / height_px * ((v-cy)*np.cos(floor_angle) + (u-cx)*np.sin(floor_angle))
+    ## With floor angle and level correction, and depth perspective correction:
+    scaling_factor = first_person_height / height_px
+    X = scaling_factor * ( \
+            ((u-cx) - Z/distance_m * (u-cu)) * np.cos(floor_angle) + \
+            ((v-cy) - Z/distance_m * (v-cv)) * np.sin(floor_angle) )
+    Y = - scaling_factor * ( \
+            ((v-cy) - Z/distance_m * (v-cv)) * np.cos(floor_angle) - \
+            ((u-cx) - Z/distance_m * (u-cu)) * np.sin(floor_angle) )
+
+    # Assemble results
     Q_coords_kpt_m = pd.DataFrame(np.array([X, Y, Z]).T, columns=Q_coords_kpt.columns)
 
     return Q_coords_kpt_m
@@ -1455,8 +1619,9 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
     pose_model = config_dict.get('pose').get('pose_model')
     mode = config_dict.get('pose').get('mode')
     det_frequency = config_dict.get('pose').get('det_frequency')
+    backend = config_dict.get('pose').get('backend')
+    device = config_dict.get('pose').get('device')
     tracking_mode = config_dict.get('pose').get('tracking_mode')
-    max_distance = config_dict.get('pose').get('max_distance', None)
     if tracking_mode == 'deepsort':
         from deep_sort_realtime.deepsort_tracker import DeepSort
         deepsort_params = config_dict.get('pose').get('deepsort_params')
@@ -1468,39 +1633,39 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
             deepsort_params = json.loads(deepsort_params)
         deepsort_tracker = DeepSort(**deepsort_params)
         deepsort_tracker.tracker.tracks.clear()
-    backend = config_dict.get('pose').get('backend')
-    device = config_dict.get('pose').get('device')
-    
+
+    keypoint_likelihood_threshold = config_dict.get('pose').get('keypoint_likelihood_threshold')
+    average_likelihood_threshold = config_dict.get('pose').get('average_likelihood_threshold')
+    keypoint_number_threshold = config_dict.get('pose').get('keypoint_number_threshold')
+    max_distance = config_dict.get('pose').get('max_distance', None)
+
     # Pixel to meters conversion
     to_meters = config_dict.get('px_to_meters_conversion').get('to_meters')
     make_c3d = config_dict.get('px_to_meters_conversion').get('make_c3d')
     save_calib = config_dict.get('px_to_meters_conversion').get('save_calib')
+    # Correct perspective effects
+    perspective_value = config_dict.get('px_to_meters_conversion', {}).get('perspective_value', 10.0)
+    perspective_unit = config_dict.get('px_to_meters_conversion', {}).get('perspective_unit', 'distance_m')
+    # Calibration from person height
+    floor_angle = config_dict.get('px_to_meters_conversion').get('floor_angle', 'auto') # 'auto' or float
+    xy_origin = config_dict.get('px_to_meters_conversion').get('xy_origin', ['auto']) # ['auto'] or [x, y]    
     # Calibration from file
     calib_file = config_dict.get('px_to_meters_conversion').get('calib_file')
     if calib_file == '': 
         calib_file = None
     else: 
-        calib_file = video_dir / calib_file
+        calib_file = Path(calib_file).resolve()
         if not calib_file.is_file():
             raise FileNotFoundError(f'Error: Could not find calibration file {calib_file}. Check that the file exists.')
-    # Calibration from person height
-    floor_angle = config_dict.get('px_to_meters_conversion').get('floor_angle') # 'auto' or float
-    floor_angle = np.radians(float(floor_angle)) if floor_angle != 'auto' else floor_angle
-    xy_origin = config_dict.get('px_to_meters_conversion').get('xy_origin') # ['auto'] or [x, y]    
-    xy_origin = [float(o) for o in xy_origin] if xy_origin != ['auto'] else 'auto'
-
-    keypoint_likelihood_threshold = config_dict.get('pose').get('keypoint_likelihood_threshold')
-    average_likelihood_threshold = config_dict.get('pose').get('average_likelihood_threshold')
-    keypoint_number_threshold = config_dict.get('pose').get('keypoint_number_threshold')
 
     # Angles advanced settings
+    display_angle_values_on = config_dict.get('angles').get('display_angle_values_on')
+    fontSize = config_dict.get('angles').get('fontSize')
+    thickness = 1 if fontSize < 0.8 else 2
     joint_angle_names = config_dict.get('angles').get('joint_angles')
     segment_angle_names = config_dict.get('angles').get('segment_angles')
     angle_names = joint_angle_names + segment_angle_names
     angle_names = [angle_name.lower() for angle_name in angle_names]
-    display_angle_values_on = config_dict.get('angles').get('display_angle_values_on')
-    fontSize = config_dict.get('angles').get('fontSize')
-    thickness = 1 if fontSize < 0.8 else 2
     flip_left_right = config_dict.get('angles').get('flip_left_right')
     correct_segment_angles_with_floor_angle = config_dict.get('angles').get('correct_segment_angles_with_floor_angle')
 
@@ -1672,7 +1837,7 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
             except:
                 logging.error('Error: Pose estimation failed. Check in Config.toml that pose_model and mode are valid.')
                 raise ValueError('Error: Pose estimation failed. Check in Config.toml that pose_model and mode are valid.')
-        logging.info(f'Persons are detected every {det_frequency} frames and tracked inbetween. Tracking is done with {tracking_mode}.')
+        logging.info(f'Persons detection is run every {det_frequency} frames (pose estimation is run at every frame). Tracking is done with {tracking_mode}.')
         
         if tracking_mode == 'deepsort': 
             logging.info(f'Deepsort parameters: {deepsort_params}.')
@@ -2112,102 +2277,100 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
         trc_data_m = []
         if to_meters and save_pose:
             logging.info('\nConverting pose to meters:')
-
+            
             # Compute height in px of the first person
             height_px = compute_height(trc_data[0].iloc[:,1:], new_keypoints_names,
                                         fastest_frames_to_remove_percent=fastest_frames_to_remove_percent, close_to_zero_speed=close_to_zero_speed_px, large_hip_knee_angles=large_hip_knee_angles, trimmed_extrema_percent=trimmed_extrema_percent)
 
-            if calib_file or save_calib:
-                dist_to_cam = 10.0 # arbitrary distance between the camera and the person (m)
+            # Compute distance from camera to compensate for perspective effects
+            distance_m = get_distance_from_camera(perspective_value=perspective_value, perspective_unit=perspective_unit, 
+                                                  calib_file=calib_file, height_px=height_px, height_m=first_person_height, 
+                                                  cam_width=cam_width, cam_height=cam_height)
+
+            # Compute floor angle and xy_origin to compensate for camera horizon and person position
+            floor_angle_estim, xy_origin_estim, gait_direction = get_floor_params(floor_angle=floor_angle, xy_origin=xy_origin, 
+                                                    calib_file=calib_file, height_px=height_px, height_m=first_person_height, 
+                                                    fps=fps, trc_data=trc_data[0], score_data=score_data[0], toe_speed_below=1, score_threshold=average_likelihood_threshold, 
+                                                    cam_width=cam_width, cam_height=cam_height)
+            cx, cy = xy_origin_estim
+            direction_person0 = 'right' if gait_direction > 0.3 \
+                                else 'left' if gait_direction < -0.3 \
+                                else 'front'
+
+            logging.info(f'Converting from pixels to meters using a person height of {first_person_height:.2f} in meters (manual input), and of {height_px:.2f} in pixels (calculated).')
+
+            perspective_messages = {
+                "distance_m": f"(obtained from a manual input).",
+                "f_px": f"(calculated from a focal length of {perspective_value:.2f} m).",
+                "fov_deg": f"(calculated from a field of view of {perspective_value:.2f} deg).",
+                "fov_rad": f"(calculated from a field of view of {perspective_value:.2f} rad).",
+                "from_calib": f"(calculated from a calibration file: {calib_file}).",
+            }
+            message = perspective_messages.get(perspective_unit, "")
+            logging.info(f'Perspective effects corrected using a camera-to-person distance of {distance_m:.2f} m {message}')
+
+            floor_angle_messages = {
+                "manual": "manual input.",
+                "auto": "gait kinematics.",
+                "from_kinematics": "gait kinematics.",
+                "from_calib": "a calibration file.",
+            }
+            if isinstance(floor_angle, (int, float)):
+                key = "manual"
+            else:
+                key = floor_angle
+            message = floor_angle_messages.get(key, "")
+            logging.info(f'Camera horizon: {np.degrees(floor_angle_estim):.2f}°, corrected using {message}')
+
+            def get_correction_message(xy_origin):
+                if all(isinstance(o, (int, float)) for o in xy_origin) and len(xy_origin) == 2:
+                    return "manual input."
+                elif xy_origin == ["auto"] or xy_origin == ["from_kinematics"]:
+                    return "gait kinematics."
+                elif xy_origin == ["from_calib"]:
+                    return "a calibration file."
+                else:
+                    return "."
+            message = get_correction_message(xy_origin)
+            logging.info(f'Floor level: {cy:.2f} px (from the top of the image), gait starting at {cx:.2f} px in the {direction_person0} direction for the first person. Corrected using {message}\n')
+
+
+            # Save calibration file
+            if save_calib and not calib_file:
                 R90z = np.array([[0.0, -1.0, 0.0],
                                 [1.0, 0.0, 0.0],
                                 [0.0, 0.0, 1.0]])
                 R270x = np.array([[1.0, 0.0, 0.0],
                                 [0.0, 0.0, 1.0],
                                 [0.0, -1.0, 0.0]])
-
-            # Compute px to meter parameters from calibration file
-            if calib_file:
-                calib_params_dict = retrieve_calib_params(calib_file)
-
-                f = calib_params_dict['K'][0][0][0]
-                first_person_height = height_px / f * dist_to_cam
-
-                R_cam = cv2.Rodrigues(calib_params_dict['R'][0])[0]
-                T_cam = np.array(calib_params_dict['T'][0])
-                R_world, T_world = world_to_camera_persp(R_cam, T_cam)
-                Rfloory = R90z.T @ R_world @ R270x.T
-                T_world = R90z.T @ T_world
-                floor_angle_estim = np.arctan2(Rfloory[0,2], Rfloory[0,0])
                 
-                cu = calib_params_dict['K'][0][0][2]
-                cv = calib_params_dict['K'][0][1][2]
-                cx = 0.0
-                cy = cv + T_world[2]*f/dist_to_cam
-                xy_origin_estim = [cx, cy]
-
-                logging.info(f'Using calibration file to convert coordinates in meters: {calib_file}.\n'
-                             f'Floor angle: {np.degrees(floor_angle_estim):.2f}°, '
-                             f'xy_origin: [{cx:.2f}, {cy:.2f}] px.')
-
+                calib_file_path = output_dir / f'{video_file_stem}_Sports2D_calib.toml'
                 
-            # Compute px to meter parameters from scene
-            else:
-                toe_speed_below = 1 # m/s (below which the foot is considered to be stationary)
-                px_per_m = height_px/first_person_height
-                toe_speed_below_px_frame = toe_speed_below * px_per_m / fps
-                if floor_angle == 'auto' or xy_origin == 'auto':
-                    # estimated from the line formed by the toes when they are on the ground (where speed = 0)
-                    try:
-                        if all(key in trc_data[0] for key in ['LBigToe', 'RBigToe']):
-                            floor_angle_estim, xy_origin_estim, _ = compute_floor_line(trc_data[0], score_data[0], keypoint_names=['LBigToe', 'RBigToe'], toe_speed_below=toe_speed_below_px_frame, score_threshold=average_likelihood_threshold)
-                        else:
-                            floor_angle_estim, xy_origin_estim, _ = compute_floor_line(trc_data[0], score_data[0], keypoint_names=['LAnkle', 'RAnkle'], toe_speed_below=toe_speed_below_px_frame, score_threshold=average_likelihood_threshold)
-                            xy_origin_estim[1] = xy_origin_estim[1] + 0.13*px_per_m # approx. height of the ankle above the floor
-                            logging.warning(f'The RBigToe and LBigToe are missing from your pose estimation model. Using ankles - 13 cm to compute the floor line.')
-                    except:
-                        floor_angle_estim = 0
-                        xy_origin_estim = cam_width/2, cam_height/2
-                        logging.warning(f'Could not estimate the floor angle and xy_origin from person {0}. Make sure that the full body is visible. Using floor angle = 0° and xy_origin = [{cam_width/2}, {cam_height/2}] px.')
-                if not floor_angle == 'auto':
-                    floor_angle_estim = floor_angle
-                if xy_origin == 'auto':
-                    cx, cy = xy_origin_estim
-                else:
-                    cx, cy = xy_origin
-                logging.info(f'Using height of person #0 ({first_person_height}m) to convert coordinates in meters.\n'
-                             f'Floor angle: {np.degrees(floor_angle_estim) if not floor_angle=="auto" else f"auto (estimation: {round(np.degrees(floor_angle_estim),2)}°)"}, '
-                             f'xy_origin: {xy_origin if not xy_origin=="auto" else f"auto (estimation: {[round(c) for c in xy_origin_estim]})"} px.')
+                # name, size, distortions
+                N = [video_file_stem]
+                S = [[cam_width, cam_height]]
+                D = [[0.0, 0.0, 0.0, 0.0]]
+
+                # Intrinsics
+                f = height_px / first_person_height * distance_m
+                cu = cam_width/2
+                cv = cam_height/2
+                K = np.array([[[f, 0.0, cu], [0.0, f, cv], [0.0, 0.0, 1.0]]])
+
+                # Extrinsics
+                Rfloory = np.array([[np.cos(floor_angle_estim), 0.0, np.sin(floor_angle_estim)],
+                                    [0.0, 1.0, 0.0],
+                                    [-np.sin(floor_angle_estim), 0.0, np.cos(floor_angle_estim)]])
+                R_world = R90z @ Rfloory @ R270x
+                T_world = R90z @ np.array([-(cx-cu)/f*distance_m, -distance_m, (cy-cv)/f*distance_m])
                 
-                # Save calibration file
-                if save_calib:
-                    calib_file_path = output_dir / f'{video_file_stem}_Sports2D_calib.toml'
-                    
-                    # name, size, distortions
-                    N = [video_file_stem]
-                    S = [[cam_width, cam_height]]
-                    D = [[0.0, 0.0, 0.0, 0.0]]
-
-                    # Intrinsics
-                    f = height_px / first_person_height * dist_to_cam
-                    cu = cam_width/2
-                    cv = cam_height/2
-                    K = np.array([[[f, 0.0, cu], [0.0, f, cv], [0.0, 0.0, 1.0]]])
-
-                    # Extrinsics
-                    Rfloory = np.array([[np.cos(floor_angle_estim), 0.0, np.sin(floor_angle_estim)],
-                                        [0.0, 1.0, 0.0],
-                                        [-np.sin(floor_angle_estim), 0.0, np.cos(floor_angle_estim)]])
-                    R_world = R90z @ Rfloory @ R270x
-                    T_world = R90z @ np.array([-(cx-cu)/f*dist_to_cam, -dist_to_cam, (cy-cv)/f*dist_to_cam])
-                    
-                    R_cam, T_cam = world_to_camera_persp(R_world, T_world)
-                    Tvec_cam = T_cam.reshape(1,3).tolist()
-                    Rvec_cam = cv2.Rodrigues(R_cam)[0].reshape(1,3).tolist()
+                R_cam, T_cam = world_to_camera_persp(R_world, T_world)
+                Tvec_cam = T_cam.reshape(1,3).tolist()
+                Rvec_cam = cv2.Rodrigues(R_cam)[0].reshape(1,3).tolist()
 
-                    # Write calibration file
-                    toml_write(calib_file_path, N, S, D, K, Rvec_cam, Tvec_cam)
-                    logging.info(f'Calibration saved to {calib_file_path}.')
+                # Write calibration file
+                toml_write(calib_file_path, N, S, D, K, Rvec_cam, Tvec_cam)
+                logging.info(f'Calibration saved to {calib_file_path}.')
 
 
             # Coordinates in m
@@ -2220,9 +2383,9 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
                     if visible_side_i == 'auto':
                         try:
                             if all(key in trc_data[i] for key in ['LBigToe', 'RBigToe']):
-                                _, _, gait_direction = compute_floor_line(trc_data[i], score_data[0], keypoint_names=['LBigToe', 'RBigToe'], toe_speed_below=toe_speed_below_px_frame, score_threshold=average_likelihood_threshold)
+                                _, _, gait_direction = compute_floor_line(trc_data[i], score_data[i], keypoint_names=['LBigToe', 'RBigToe'], score_threshold=keypoint_likelihood_threshold) # toe_speed_below=1 bu default 
                             else:
-                                _, _, gait_direction = compute_floor_line(trc_data[i], score_data[0], keypoint_names=['LAnkle', 'RAnkle'], toe_speed_below=toe_speed_below_px_frame, score_threshold=average_likelihood_threshold)
+                                _, _, gait_direction = compute_floor_line(trc_data[i], score_data[i], keypoint_names=['LAnkle', 'RAnkle'], score_threshold=keypoint_likelihood_threshold)
                                 logging.warning(f'The RBigToe and LBigToe are missing from your model. Gait direction will be determined from the ankle points.')
                             visible_side_i = 'right' if gait_direction > 0.3 \
                                                 else 'left' if gait_direction < -0.3 \
@@ -2237,8 +2400,9 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
                     else:
                         logging.info(f'- Person {i}: Seen from the {visible_side_i}.')
                     
+
                     # Convert to meters
-                    px_to_m_i = [convert_px_to_meters(trc_data[i][kpt_name], first_person_height, height_px, cx, cy, -floor_angle_estim, visible_side=visible_side_i) for kpt_name in new_keypoints_names]
+                    px_to_m_i = [convert_px_to_meters(trc_data[i][kpt_name], first_person_height, height_px, distance_m, cam_width, cam_height, cx, cy, -floor_angle_estim, visible_side=visible_side_i) for kpt_name in new_keypoints_names]
                     trc_data_m_i = pd.concat([all_frames_time.rename('time')]+px_to_m_i, axis=1)
                     for c_id, c in enumerate(3*np.arange(len(trc_data_m_i.columns[3::3]))+1): # only X coordinates
                         first_run_start, last_run_end = first_run_starts_everyone[i][c_id], last_run_ends_everyone[i][c_id]
@@ -2247,7 +2411,7 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
                         trc_data_m_i.iloc[first_run_start:last_run_end,c+2] = trc_data_m_i.iloc[first_run_start:last_run_end,c+2].ffill().bfill()
                     first_trim, last_trim = trc_data_m_i.isnull().any(axis=1).idxmin(), trc_data_m_i[::-1].isnull().any(axis=1).idxmin()
                     trc_data_m_i = trc_data_m_i.iloc[first_trim:last_trim+1,:]
-                    px_to_m_unfiltered_i = [convert_px_to_meters(trc_data_unfiltered[i][kpt_name], first_person_height, height_px, cx, cy, -floor_angle_estim) for kpt_name in new_keypoints_names]
+                    px_to_m_unfiltered_i = [convert_px_to_meters(trc_data_unfiltered[i][kpt_name], first_person_height, height_px, distance_m, cam_width, cam_height, cx, cy, -floor_angle_estim, visible_side=visible_side_i) for kpt_name in new_keypoints_names]
                     trc_data_unfiltered_m_i = pd.concat([all_frames_time.rename('time')]+px_to_m_unfiltered_i, axis=1)
 
                     if to_meters and (show_plots or save_plots):
@@ -2531,7 +2695,7 @@ def process_fun(config_dict, video_file, time_range, frame_rate, result_dir):
                         if (mot_file.parent/(mot_file.stem+'_ik.mot')).exists():
                             os.remove(mot_file.parent/(mot_file.stem+'_ik.mot'))
                         os.rename(mot_file, mot_file.parent/(mot_file.stem+'_ik.mot'))
-                    logging.info(f'.osim model and .mot motion file results saved to {kinematics_dir.resolve()}.\n')
+                    logging.info(f'.osim model and .mot motion file results saved to {kinematics_dir.resolve().parent}.\n')
                             
             # Move all files in pose-3d and kinematics to the output_dir
             osim.Logger.removeFileSink()

{sports2d-0.8.24.dist-info → sports2d-0.8.25.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sports2d
-Version: 0.8.24
+Version: 0.8.25
 Summary: Compute 2D human pose and angles from a video or a webcam.
 Author-email: David Pagnon <contact@david-pagnon.com>
 Maintainer-email: David Pagnon <contact@david-pagnon.com>
@@ -52,7 +52,7 @@ Dynamic: license-file
 </br>
 
 > **`Announcements:`**
-> - Generate or import a calibration file, OpenSim skeleton overlay **New in v0.9!** 
+> - Compensate for floor angle, floor height, depth perspective effects, generate a calibration file **New in v0.9!** 
 > - Select only the persons you want to analyze **New in v0.8!** 
 > - MarkerAugmentation and Inverse Kinematics for accurate 3D motion with OpenSim. **New in v0.7!** 
 > - Any detector and pose estimation model can be used. **New in v0.6!**
@@ -294,30 +294,35 @@ sports2d --person_ordering_method on_click
 #### Get coordinates in meters: 
 > **N.B.:** The Z coordinate (depth) should not be overly trusted. 
 
-You may want coordinates in meters rather than pixels. 2 options to do so:
+To convert from pixels to meters, you need a minima the height of a participant. Better results can be obtained by also providing an information on depth. The camera horizon angle and the floor height are generally automatically estimated. **N.B.: A calibration file will be generated.** 
 
-1. **Just provide the height of a reference person**:
-   - Their height in meters is be compared with their height in pixels to get a pixel-to-meter conversion factor.
-   - To estimate the depth coordinates, specify which side of the person is visible: `left`, `right`, `front`, or `back`. Use `auto` if you want it to be automatically determined (only works for motions in the sagittal plane), or `none` if you want to keep 2D coordinates instead of 3D (if the person turns around, for example).
-   - The floor angle is automatically estimated from gait, as well as the origin of the xy axis. The person trajectory is corrected accordingly. You can use the `--floor_angle` and `--xy_origin` parameters to manually specify them if your subject is not travelling horizontally or if you want the origin not to be under their feet (note that the `y` axis points down).
-   
-   **N.B.: A calibration file will be generated.** By convention, the camera-to-subject distance is set to 10 meters.
+- The pixel-to-meters scale is computed from the ratio between the height of the participant in meters and in pixels. The height in pixels is automatically calculated; use the `--first_person_height` parameter to specify the height in meters.
+- Depth perspective effects can be compensated either with the camera-to-person distance (m), or focal length (px), or field-of-view (degrees or radians), or from a calibration file. Use the `--perspective_unit` ('distance_m', 'f_px', 'fov_deg', 'fov_rad', or 'from_calib') and `--perspective_value` parameters (resp. in m, px, deg, rad, or '').
+- The camera horizon angle can be estimated from kinematics (`auto`), from a calibration file (`from_calib`), or manually (float). Use the `--floor_angle` parameter.
+- Likewise for the floor level. Use the `--xy_origin` parameter.
 
-   ``` cmd
-   sports2d --first_person_height 1.65 --visible_side auto front none
-   ```
-   ``` cmd
-   sports2d --first_person_height 1.65 --visible_side auto front none `
-            --person_ordering_method on_click `
-            --floor_angle 0 --xy_origin 0 940
-   ```
+If one of these parameters is set to `from_calib`, then use `--calib_file`.
 
-2. **Or use a calibration file**:\
-  It can either be a `.toml` calibration file previously generated by Sports2D, or a more accurate one coming from another system. For example, [Pose2Sim](https://github.com/perfanalytics/pose2sim) can be used to accurately calculate calibration, or to convert calibration files from Qualisys, Vicon, OpenCap, FreeMoCap, etc.
 
-   ``` cmd
-   sports2d --calib_file Calib_demo.toml --visible_side auto front none
-   ```
+``` cmd
+sports2d --first_person_height 1.65
+```
+``` cmd
+sports2d --first_person_height 1.65 `
+        --floor_angle auto `
+        --xy_origin auto`
+        --perspective_unit distance_m --perspective_value 10
+```
+``` cmd
+sports2d --first_person_height 1.65 `
+        --floor_angle 0 `
+        --xy_origin from_calib`
+        --perspective_unit from_calib --calib_file Sports2D\Demo\Calib_demo.toml
+```
+``` cmd
+sports2d --first_person_height 1.65 `
+        --perspective_unit f_px --perspective_value 2520
+```
 
 <br>
 
@@ -480,20 +485,25 @@ sports2d --help
 'config': ["C", "path to a toml configuration file"],
 
 'video_input': ["i", "webcam, or video_path.mp4, or video1_path.avi video2_path.mp4 ... Beware that images won't be saved if paths contain non ASCII characters"],
+'time_range': ["t", "start_time end_time. In seconds. Whole video if not specified. start_time1 end_time1 start_time2 end_time2 ... if multiple videos with different time ranges"],
 'nb_persons_to_detect': ["n", "number of persons to detect. int or 'all'. 'all' if not specified"],
 'person_ordering_method': ["", "'on_click', 'highest_likelihood', 'largest_size', 'smallest_size', 'greatest_displacement', 'least_displacement', 'first_detected', or 'last_detected'. 'on_click' if not specified"],
 'first_person_height': ["H", "height of the reference person in meters. 1.65 if not specified. Not used if a calibration file is provided"],
 'visible_side': ["", "front, back, left, right, auto, or none. 'auto front none' if not specified. If 'auto', will be either left or right depending on the direction of the motion. If 'none', no IK for this person"],
+'participant_mass': ["", "mass of the participant in kg or none. Defaults to 70 if not provided. No influence on kinematics (motion), only on kinetics (forces)"],
+'perspective_value': ["", "Either camera-to-person distance (m), or focal length (px), or field-of-view (degrees or radians), or '' if perspective_unit=='from_calib'"],
+'perspective_unit': ["", "'distance_m', 'f_px', 'fov_deg', 'fov_rad', or 'from_calib'"],
+'do_ik': ["", "do inverse kinematics. false if not specified"],
+'use_augmentation': ["", "Use LSTM marker augmentation. false if not specified"],
 'load_trc_px': ["", "load trc file to avaid running pose estimation again. false if not specified"],
 'compare': ["", "visually compare motion with trc file. false if not specified"],
-'webcam_id': ["w", "webcam ID. 0 if not specified"],
-'time_range': ["t", "start_time end_time. In seconds. Whole video if not specified. start_time1 end_time1 start_time2 end_time2 ... if multiple videos with different time ranges"],
 'video_dir': ["d", "current directory if not specified"],
 'result_dir': ["r", "current directory if not specified"],
+'webcam_id': ["w", "webcam ID. 0 if not specified"],
 'show_realtime_results': ["R", "show results in real-time. true if not specified"],
 'display_angle_values_on': ["a", '"body", "list", "body" "list", or "none". body list if not specified'],
 'show_graphs': ["G", "show plots of raw and processed results. true if not specified"],
-'save_graphs': ["", "save position and angle plots of raw and processed results. false if not specified"],
+'save_graphs': ["", "save position and angle plots of raw and processed results. true if not specified"],
 'joint_angles': ["j", '"Right ankle" "Left ankle" "Right knee" "Left knee" "Right hip" "Left hip" "Right shoulder" "Left shoulder" "Right elbow" "Left elbow" if not specified'],
 'segment_angles': ["s", '"Right foot" "Left foot" "Right shank" "Left shank" "Right thigh" "Left thigh" "Pelvis" "Trunk" "Shoulders" "Head" "Right arm" "Left arm" "Right forearm" "Left forearm" if not specified'],
 'save_vid': ["V", "save processed video. true if not specified"],
@@ -514,11 +524,8 @@ sports2d --help
 'xy_origin': ["", "origin of the xy plane. 'auto' if not specified"],
 'calib_file': ["", "path to calibration file. '' if not specified, eg no calibration file"],
 'save_calib': ["", "save calibration file. true if not specified"],
-'do_ik': ["", "do inverse kinematics. false if not specified"],
-'use_augmentation': ["", "Use LSTM marker augmentation. false if not specified"],
 'feet_on_floor': ["", "offset marker augmentation results so that feet are at floor level. true if not specified"],
-'use_simple_model': ["", "IK 10+ times faster, but no muscles or flexible spine. false if not specified"],
-'participant_mass': ["", "mass of the participant in kg or none. Defaults to 70 if not provided. No influence on kinematics (motion), only on kinetics (forces)"],
+'use_simple_model': ["", "IK 10+ times faster, but no muscles or flexible spine, no patella. false if not specified"],
 'close_to_zero_speed_m': ["","Sum for all keypoints: about 50 px/frame or 0.2 m/frame"], 
 'tracking_mode': ["", "'sports2d' or 'deepsort'. 'deepsort' is slower, harder to parametrize but can be more robust if correctly tuned"],
 'deepsort_params': ["", 'Deepsort tracking parameters: """{dictionary between 3 double quotes}""". \n\
@@ -528,6 +535,7 @@ sports2d --help
 'keypoint_likelihood_threshold': ["", "detected keypoints are not retained if likelihood is below this threshold. 0.3 if not specified"],
 'average_likelihood_threshold': ["", "detected persons are not retained if average keypoint likelihood is below this threshold. 0.5 if not specified"],
 'keypoint_number_threshold': ["", "detected persons are not retained if number of detected keypoints is below this threshold. 0.3 if not specified, i.e., i.e., 30 percent"],
+'max_distance': ["", "If a person is detected further than max_distance from its position on the previous frame, it will be considered as a new one. in px or None, 100 by default."],
 'fastest_frames_to_remove_percent': ["", "Frames with high speed are considered as outliers. Defaults to 0.1"],
 'close_to_zero_speed_px': ["", "Sum for all keypoints: about 50 px/frame or 0.2 m/frame. Defaults to 50"],
 'large_hip_knee_angles': ["", "Hip and knee angles below this value are considered as imprecise. Defaults to 45"],
@@ -539,15 +547,16 @@ sports2d --help
 'interp_gap_smaller_than': ["", "interpolate sequences of missing data if they are less than N frames long. 10 if not specified"],
 'fill_large_gaps_with': ["", "last_value, nan, or zeros. last_value if not specified"],
 'sections_to_keep': ["", "all, largest, first, or last.  Keep 'all' valid sections even when they are interspersed with undetected chunks, or the 'largest' valid section, or the 'first' one, or the 'last' one"],
+'min_chunk_size': ["", "Minimum number of valid frames in a row to keep a chunk of data for a person.  10 if not specified"],
 'reject_outliers': ["", "reject outliers with Hampel filter before other filtering methods. true if not specified"],
 'filter': ["", "filter results. true if not specified"],
 'filter_type': ["", "butterworth, kalman, gcv_spline, gaussian, median, or loess. butterworth if not specified"],
+'cut_off_frequency': ["", "cut-off frequency of the Butterworth filter. 6 if not specified"],
 'order': ["", "order of the Butterworth filter. 4 if not specified"],
-'cut_off_frequency': ["", "cut-off frequency of the Butterworth filter. 3 if not specified"],
+'gcv_cut_off_frequency': ["", "cut-off frequency of the GCV spline filter. 'auto' is usually better, unless the signal is too short (noise can then be considered as signal -> trajectories not filtered). 'auto' if not specified"],
+'gcv_smoothing_factor': ["", "smoothing factor of the GCV spline filter (>=0). Ignored if cut_off_frequency != 'auto'. Biases results towards more smoothing (>1) or more fidelity to data (<1). 1.0 if not specified"],
 'trust_ratio': ["", "trust ratio of the Kalman filter: How much more do you trust triangulation results (measurements), than the assumption of constant acceleration(process)? 500 if not specified"],
 'smooth': ["", "dual Kalman smoothing. true if not specified"],
-'gcv_cut_off_frequency': ["", "cut-off frequency of the GCV spline filter. 'auto' if not specified"],
-'smoothing_factor': ["", "smoothing factor of the GCV spline filter (>=0). Ignored if cut_off_frequency != 'auto'. Biases results towards more smoothing (>1) or more fidelity to data (<1). 0.1 if not specified"],
 'sigma_kernel': ["", "sigma of the gaussian filter. 1 if not specified"],
 'nb_values_used': ["", "number of values used for the loess filter. 5 if not specified"],
 'kernel_size': ["", "kernel size of the median filter. 3 if not specified"],
@@ -656,11 +665,11 @@ Sports2D:
 
 2. **Sets up pose estimation with RTMLib.** It can be run in lightweight, balanced, or performance mode, and for faster inference, the person bounding boxes can be tracked instead of detected every frame. Any RTMPose model can be used. 
 
-3. **Tracks people** so that their IDs are consistent across frames. A person is associated to another in the next frame when they are at a small distance. IDs remain consistent even if the person disappears from a few frames. We crafted a 'sports2D' tracker which gives good results and runs in real time, but it is also possible to use `deepsort` in particularly challenging situations. 
+3. **Tracks people** so that their IDs are consistent across frames. A person is associated to another in the next frame when they are at a small distance. IDs remain consistent even if the person disappears from a few frames, thanks to the 'sports2D' tracker. [See Release notes of v0.8.22 for more information](https://github.com/davidpagnon/Sports2D/releases/tag/v0.8.22). 
 
 4. **Chooses which persons to analyze.** In single-person mode, only keeps the person with the highest average scores over the sequence. In multi-person mode, you can choose the number of persons to analyze (`nb_persons_to_detect`), and how to order them (`person_ordering_method`). The ordering method can be 'on_click', 'highest_likelihood', 'largest_size', 'smallest_size', 'greatest_displacement', 'least_displacement', 'first_detected', or 'last_detected'. `on_click` is default and lets the user click on the persons they are interested in, in the desired order.
 
-4. **Converts the pixel coordinates to meters.** The user can provide the size of a specified person to scale results accordingly. The floor angle and the coordinate origin can either be detected automatically from the gait sequence, or be manually specified. The depth coordinates are set to normative values, depending on whether the person is going left, right, facing the camera, or looking away.
+4. **Converts the pixel coordinates to meters.** The user can provide the size of a specified person to scale results accordingly. The camera horizon angle and the floor level can either be detected automatically from the gait sequence, be manually specified, or obtained frmm a calibration file. The depth perspective effects are compensated thanks with the distance from the camera to the subject, the focal length, the field of view, or from a calibration file. [See Release notes of v0.8.25 for more information](https://github.com/davidpagnon/Sports2D/releases/tag/v0.8.25). 
 
 5. **Computes the selected joint and segment angles**, and flips them on the left/right side if the respective foot is pointing to the left/right. 
 

{sports2d-0.8.24.dist-info → sports2d-0.8.25.dist-info}/RECORD

@@ -9,18 +9,18 @@ Content/paper.md,sha256=8rWSOLrKTysloZv0Fz2lr3nayxtHi7GlFMqwdgDVggY,11333
 Content/sports2d_blender.gif,sha256=wgMuPRxhja3XtQn76_okGXsNnUT9Thp0pnD36GdW5_E,448786
 Content/sports2d_opensim.gif,sha256=XP1AcjqhbGcJknXUoNJjPWAwaM9ahZafbDgLWvzKJs4,376656
 Sports2D/Sports2D.ipynb,sha256=VnOVjIl6ndnCJTT13L4W5qTw4T-TQDF3jt3-wxnXDqM,2427047
-Sports2D/Sports2D.py,sha256=dZR16Id9rhrifEU91Y6wZxxmCCQDuGEfa3Ri9kLSiR4,36345
+Sports2D/Sports2D.py,sha256=kayxoFmZyekSoO6YDipLMPUW9cHSCRReaymd_Va8AQA,36761
 Sports2D/__init__.py,sha256=BuUkPEdItxlkeqz4dmoiPwZLkgAfABJK3KWQ1ujTGwE,153
-Sports2D/process.py,sha256=TweN8PsBuA8FG-7-yAQEGh_PJYpmhGDeNYtde40XXcc,131637
+Sports2D/process.py,sha256=TX9ne0Wp1WxJPtSqzAkV-0rZcWWPlLVdDUqIPkqo5Wo,140354
 Sports2D/Demo/Calib_demo.toml,sha256=d6myoOkhhz3c5LOwCEJQBWT9eyqr6RSYoaPbFjBMizc,369
-Sports2D/Demo/Config_demo.toml,sha256=ZCyGybTRPi3YNTigPZkyokQz5gbEsbqGAS4O7Z69K4M,15972
+Sports2D/Demo/Config_demo.toml,sha256=w9PaAZFPMHLKmWtPpEV_vWrUReyAZpH6iLa2-D8qhJ8,16545
 Sports2D/Demo/demo.mp4,sha256=2aZkFxhWR7ESMEtXCT8MGA83p2jmoU2sp1ylQfO3gDk,3968304
 Sports2D/Utilities/__init__.py,sha256=BuUkPEdItxlkeqz4dmoiPwZLkgAfABJK3KWQ1ujTGwE,153
-Sports2D/Utilities/common.py,sha256=idMRmesFv5BPX-5g3z5dOVa7SpS_8tNgijvGrOZlR-k,11185
-Sports2D/Utilities/tests.py,sha256=BcZ02nVcX04PpTQ2t0g5dPGHbAXY_028Y2lxn_3udjQ,5570
-sports2d-0.8.24.dist-info/licenses/LICENSE,sha256=f4qe3nE0Y7ltJho5w-xAR0jI5PUox5Xl-MsYiY7ZRM8,1521
-sports2d-0.8.24.dist-info/METADATA,sha256=6DjTjB4xYYmTItINASrlzONHW65ww6Py3bhhxjGSR9g,42938
-sports2d-0.8.24.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-sports2d-0.8.24.dist-info/entry_points.txt,sha256=V8dFDIXatz9VvoGgoHzb2wE71C9-f85K6_OjnEQlxww,108
-sports2d-0.8.24.dist-info/top_level.txt,sha256=cWWBiDD2WbQXMoIoN6-9et9U2t2c_ZKo2JtBqO5uN-k,17
-sports2d-0.8.24.dist-info/RECORD,,
+Sports2D/Utilities/common.py,sha256=RbS7kFCAT7SLbCxJJM0ULsqm7G4TMCnOVeZDTRgkrwk,11457
+Sports2D/Utilities/tests.py,sha256=DYQ5ZdO1L7ZxxSb5hx8rTbF9VaKBeyh16hK_j_6Q9hQ,5819
+sports2d-0.8.25.dist-info/licenses/LICENSE,sha256=f4qe3nE0Y7ltJho5w-xAR0jI5PUox5Xl-MsYiY7ZRM8,1521
+sports2d-0.8.25.dist-info/METADATA,sha256=0q1giYFQLJRODB4XskE2bHce6EcpmKV2v-O5287rVxM,43757
+sports2d-0.8.25.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+sports2d-0.8.25.dist-info/entry_points.txt,sha256=V8dFDIXatz9VvoGgoHzb2wE71C9-f85K6_OjnEQlxww,108
+sports2d-0.8.25.dist-info/top_level.txt,sha256=cWWBiDD2WbQXMoIoN6-9et9U2t2c_ZKo2JtBqO5uN-k,17
+sports2d-0.8.25.dist-info/RECORD,,