Skip to content

Commit d59328d

Browse files
deruyter92deruyter92
committed
docs: convert docstrings to Google style (batch A2)
1 parent 2078850 commit d59328d

5 files changed

Lines changed: 168 additions & 268 deletions

File tree

‎deeplabcut/gui/tabs/label_frames.py‎

Lines changed: 27 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -35,40 +35,35 @@ def label_frames(config_path: str | Path | None = None, image_folder: str | None
3535
`image_folder` for the project is opened in the napari-deeplabcut GUI to be labeled.
3636
If only the `config_path` is given, the first image folder is opened.
3737
38-
Parameters
39-
----------
40-
config_path: str, Path, None
41-
Full path of the project config.yaml file.
42-
43-
image_folder: str, None
44-
Name of the image folder to open for labelling.
38+
Args:
39+
config_path (str, Path, None): Full path of the project config.yaml file.
40+
image_folder (str, None): Name of the image folder to open for labelling.
4541
4642
Examples:
47-
--------
48-
Opening the napari-deeplabcut annotation GUI without opening a specific folder of
49-
images to label. You then need to drag-and-drop your image folder into the GUI.
50-
See the napari-deeplabcut docs linked above for more information about labelling in
51-
napari-deeplabcut.
52-
>>> import deeplabcut
53-
>>> deeplabcut.label_frames()
54-
55-
Opening the images extracted from the "2025-01-01-experiment7" video in
56-
napari-deeplabcut on Windows. The project's folder structure should look as follows:
57-
reaching-task/ # project root directory
58-
├── config.yaml # project configuration file
59-
└── labeled-data/ # folder containing all extracted image folders
60-
├── ...
61-
├── 2025-01-01-experiment7 # folder containing the images to label
62-
└── ...
63-
64-
>>> deeplabcut.label_frames(
65-
>>> "C:\\myproject\\reaching-task\\config.yaml",
66-
>>> "2025-01-01-experiment7",
67-
>>> )
68-
69-
Opening the images extracted from the first video listed in the project
70-
configuration in napari-deeplabcut on a Unix system.
71-
>>> deeplabcut.label_frames("/users/john/project/config.yaml")
43+
Opening the napari-deeplabcut annotation GUI without opening a specific folder of
44+
images to label. You then need to drag-and-drop your image folder into the GUI.
45+
See the napari-deeplabcut docs linked above for more information about labelling in
46+
napari-deeplabcut.
47+
>>> import deeplabcut
48+
>>> deeplabcut.label_frames()
49+
50+
Opening the images extracted from the "2025-01-01-experiment7" video in
51+
napari-deeplabcut on Windows. The project's folder structure should look as follows:
52+
reaching-task/ # project root directory
53+
├── config.yaml # project configuration file
54+
└── labeled-data/ # folder containing all extracted image folders
55+
├── ...
56+
├── 2025-01-01-experiment7 # folder containing the images to label
57+
└── ...
58+
59+
>>> deeplabcut.label_frames(
60+
>>> "C:\\myproject\\reaching-task\\config.yaml",
61+
>>> "2025-01-01-experiment7",
62+
>>> )
63+
64+
Opening the images extracted from the first video listed in the project
65+
configuration in napari-deeplabcut on a Unix system.
66+
>>> deeplabcut.label_frames("/users/john/project/config.yaml")
7267
"""
7368
files = None
7469
if config_path is None:

‎deeplabcut/gui/tracklet_toolbox.py‎

Lines changed: 23 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -927,8 +927,8 @@ def refine_tracklets(
927927
max_gap=2,
928928
trail_len=0,
929929
):
930-
"""
931-
Refine tracklets stored either in pickle or h5 format.
930+
"""Refine tracklets stored either in pickle or h5 format.
931+
932932
The procedure is done in two stages:
933933
(i) freshly-converted detections are read by the TrackletManager,
934934
which automatically attempts to optimize tracklet continuity by
@@ -940,40 +940,27 @@ def refine_tracklets(
940940
selected using the Lasso tool in order to re-assign multiple tracks
941941
to another identity at once.
942942
943-
Parameters
944-
----------
945-
config: str
946-
Full path of the config.yaml file.
947-
948-
pickle_or_h5_file: str
949-
Full path of either the pickle file obtained after calling
950-
deeplabcut.convert_detections2tracklets, or the h5 file written after
951-
refining the tracklets a first time. Note that refined tracklets are
952-
always stored in the h5 format.
953-
954-
video: str
955-
Full path of the corresponding video.
956-
If the video duration and the total length of the tracklets disagree
957-
by more than 5%, a message is printed indicating that the selected
958-
video may not be the right one.
959-
960-
min_swap_len : float, optional (default=2)
961-
Minimum swap length.
962-
Set to 2 by default. Retained swaps appear in the right panel in
963-
shaded regions.
964-
965-
min_tracklet_len : float, optional (default=2)
966-
Minimum tracklet length.
967-
By default, tracklets shorter than 2 frames are discarded,
968-
leaving missing data instead. If set to 0, all tracklets are kept.
969-
970-
max_gap : int, optional (default=2).
971-
Maximal gap size (in number of frames) of missing data to be filled.
972-
The procedure fits a cubic spline over all individual trajectories,
973-
and fills all gaps smaller than or equal to 2 frames by default.
974-
975-
trail_len : int, optional (default=0)
976-
Number of trailing points. None by default, to accelerate visualization.
943+
Args:
944+
config (str): Full path of the config.yaml file.
945+
pickle_or_h5_file (str): Full path of either the pickle file obtained after calling
946+
deeplabcut.convert_detections2tracklets, or the h5 file written after
947+
refining the tracklets a first time. Note that refined tracklets are
948+
always stored in the h5 format.
949+
video (str): Full path of the corresponding video.
950+
If the video duration and the total length of the tracklets disagree
951+
by more than 5%, a message is printed indicating that the selected
952+
video may not be the right one.
953+
min_swap_len (float, optional): Minimum swap length.
954+
Set to 2 by default. Retained swaps appear in the right panel in
955+
shaded regions. Defaults to 2.
956+
min_tracklet_len (float, optional): Minimum tracklet length.
957+
By default, tracklets shorter than 2 frames are discarded,
958+
leaving missing data instead. If set to 0, all tracklets are kept. Defaults to 2.
959+
max_gap (int, optional): Maximal gap size (in number of frames) of missing data to be filled.
960+
The procedure fits a cubic spline over all individual trajectories,
961+
and fills all gaps smaller than or equal to 2 frames by default. Defaults to 2.
962+
trail_len (int, optional): Number of trailing points. None by default, to accelerate visualization.
963+
Defaults to 0.
977964
"""
978965
manager = TrackletManager(config, min_swap_len, min_tracklet_len, max_gap)
979966
if pickle_or_h5_file.endswith("pickle"):

‎deeplabcut/pose_estimation_3d/camera_calibration.py‎

Lines changed: 33 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -26,9 +26,7 @@
2626

2727

2828
def calibrate_cameras(config, cbrow=8, cbcol=6, calibrate=False, alpha=0.4, search_window_size=(11, 11)):
29-
"""This function extracts the corners points from the calibration images, calibrates
30-
the camera and stores the calibration files in the project folder (defined in the
31-
config file).
29+
"""Extract corner points from calibration images, calibrate cameras, and store results.
3230
3331
Make sure you have around 20-60 pairs of calibration images.
3432
The function should be used iteratively to select the right set of calibration images.
@@ -43,39 +41,27 @@ def calibrate_cameras(config, cbrow=8, cbcol=6, calibrate=False, alpha=0.4, sear
4341
Once the right number of calibration images are selected,
4442
use the parameter ``calibrate=True`` to calibrate the cameras.
4543
46-
Parameters
47-
----------
48-
config : string
49-
Full path of the config.yaml file as a string.
50-
51-
cbrow : int
52-
Integer specifying the number of rows in the calibration image.
53-
54-
cbcol : int
55-
Integer specifying the number of columns in the calibration image.
56-
57-
calibrate : bool
58-
If this is set to True, the cameras are calibrated with the current set of calibration images.
59-
The default is ``False``
60-
Set it to True, only after checking the results of the corner detection method
61-
and removing dysfunctional images!
62-
63-
alpha: float
64-
Floating point number between 0 and 1 specifying the free scaling parameter.
65-
When alpha = 0, the rectified images with only valid pixels are stored
66-
i.e. the rectified images are zoomed in. When alpha = 1, all the pixels from the original images are retained.
67-
For more details: https://docs.opencv.org/2.4/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html
68-
69-
search_window_size: tuple of int
70-
Half of the side length of the search window when refining detected checkerboard corners for subpixel accuracy.
71-
72-
Example:
73-
--------
74-
Linux/MacOs/Windows
75-
>>> deeplabcut.calibrate_camera(config)
76-
77-
Once the right set of calibration images are selected,
78-
>>> deeplabcut.calibrate_camera(config, calibrate=True)
44+
Args:
45+
config (string): Full path of the config.yaml file as a string.
46+
cbrow (int): Integer specifying the number of rows in the calibration image.
47+
cbcol (int): Integer specifying the number of columns in the calibration image.
48+
calibrate (bool): If True, calibrate cameras with the current calibration images.
49+
Set to True only after checking corner detection and removing bad images.
50+
Defaults to False.
51+
alpha (float): Free scaling parameter between 0 and 1.
52+
When alpha = 0, rectified images with only valid pixels are stored (zoomed in).
53+
When alpha = 1, all pixels from the original images are retained.
54+
For more details:
55+
https://docs.opencv.org/2.4/modules/calib3d/doc/camera_calibration_and_3d_reconstruction.html
56+
search_window_size (tuple of int): Half of the side length of the search window when
57+
refining detected checkerboard corners for subpixel accuracy.
58+
59+
Examples:
60+
Linux/MacOs/Windows
61+
>>> deeplabcut.calibrate_camera(config)
62+
63+
Once the right set of calibration images are selected,
64+
>>> deeplabcut.calibrate_camera(config, calibrate=True)
7965
"""
8066
# Termination criteria
8167
criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 30, 0.001)
@@ -283,29 +269,20 @@ def calibrate_cameras(config, cbrow=8, cbcol=6, calibrate=False, alpha=0.4, sear
283269

284270

285271
def check_undistortion(config, cbrow=8, cbcol=6, plot=True):
286-
"""This function undistorts the calibration images based on the camera matrices and
287-
stores them in the project folder(defined in the config file) to visually check if
288-
the camera matrices are correct.
289-
290-
Parameters
291-
----------
292-
config : string
293-
Full path of the config.yaml file as a string.
294-
295-
cbrow : int
296-
Int specifying the number of rows in the calibration image.
272+
"""Undistort calibration images and store them for visual inspection.
297273
298-
cbcol : int
299-
Int specifying the number of columns in the calibration image.
274+
Uses camera matrices from calibration to verify they are correct.
300275
301-
plot : bool
302-
If this is set to True, the results of undistortion are saved as plots.
303-
The default is ``True``; if provided it must be either ``True`` or ``False``.
276+
Args:
277+
config (string): Full path of the config.yaml file as a string.
278+
cbrow (int): Number of rows in the calibration image.
279+
cbcol (int): Number of columns in the calibration image.
280+
plot (bool): If True, save undistortion results as plots.
281+
Must be either ``True`` or ``False`` if provided. Defaults to True.
304282
305-
Example:
306-
--------
307-
Linux/MacOs/Windows
308-
>>> deeplabcut.check_undistortion(config, cbrow=8, cbcol=6)
283+
Examples:
284+
Linux/MacOs/Windows
285+
>>> deeplabcut.check_undistortion(config, cbrow=8, cbcol=6)
309286
"""
310287
# Read the config file
311288
criteria = (cv2.TERM_CRITERIA_EPS + cv2.TERM_CRITERIA_MAX_ITER, 30, 0.001)

‎deeplabcut/pose_estimation_3d/plotting3D.py‎

Lines changed: 36 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -72,80 +72,42 @@ def create_labeled_video_3d(
7272
fps=30,
7373
dpi=300,
7474
):
75-
"""Creates a video with views from the two cameras and the 3d reconstruction for a
76-
selected number of frames.
77-
78-
Parameters
79-
----------
80-
config : string
81-
Full path of the config.yaml file as a string.
82-
83-
path : list
84-
A list of strings containing the full paths to triangulated files for analysis or a path to the directory,
85-
where all the triangulated files are stored.
86-
87-
videofolder: string
88-
Full path of the folder where the videos are stored.
89-
Use this if the videos are stored in a different location other than
90-
where the triangulation files are stored.
91-
By default is ``None`` and therefore looks for video files in the
92-
directory where the triangulation file is stored.
93-
94-
start: int
95-
Integer specifying the start of frame index to select.
96-
Default is set to 0.
97-
98-
end: int
99-
Integer specifying the end of frame index to select.
100-
Default is set to None, where all the frames of the video are used for creating the labeled video.
101-
102-
trailpoints: int
103-
Number of revious frames whose body parts are plotted in a frame (for displaying history).
104-
Default is set to 0.
105-
106-
videotype: string, optional
107-
Checks for the extension of the video in case the input to the video is a directory.\n
108-
Only videos with this extension are analyzed.
109-
If left unspecified, videos with common extensions ('avi', 'mp4', 'mov', 'mpeg', 'mkv') are kept.
110-
111-
view: list
112-
A list that sets the elevation angle in z plane and azimuthal angle in x,y plane of 3d view.
113-
Useful for rotating the axis for 3d view
114-
115-
xlim: list
116-
A list of integers specifying the limits for xaxis of 3d view.
117-
By default it is set to [None,None], where the x limit is set by t
118-
aking the minimum and maximum value of the x coordinates for all the bodyparts.
119-
120-
ylim: list
121-
A list of integers specifying the limits for yaxis of 3d view.
122-
By default it is set to [None,None], where the y limit is set by
123-
taking the minimum and maximum value of the y coordinates for all the bodyparts.
124-
125-
zlim: list
126-
A list of integers specifying the limits for zaxis of 3d view.
127-
By default it is set to [None,None], where the z limit is set by
128-
taking the minimum and maximum value of the z coordinates for all the bodyparts.
129-
130-
draw_skeleton: bool
131-
If ``True`` adds a line connecting the body parts making a skeleton on on each frame.
132-
The body parts to be connected and the color of these connecting lines are specified in the config file.
133-
By default: ``True``
134-
135-
color_by : string, optional (default='bodypart')
136-
Coloring rule. By default, each bodypart is colored differently.
137-
If set to 'individual', points belonging to a single individual are colored the same.
138-
139-
Example:
140-
-------
141-
Linux/MacOs
142-
>>> deeplabcut.create_labeled_video_3d(config, ["/data/project1/videos/3d.h5"], start=100, end=500)
143-
144-
To create labeled videos for all the triangulated files in the folder
145-
>>> deeplabcut.create_labeled_video_3d(config, ["/data/project1/videos"], start=100, end=500)
146-
147-
To set the xlim, ylim, zlim and rotate the view of the 3d axis
148-
>>> deeplabcut.create_labeled_video_3d(config,['/data/project1/videos'],start=100,
75+
"""Create a video with two camera views and 3D reconstruction for selected frames.
76+
77+
Args:
78+
config (string): Full path of the config.yaml file as a string.
79+
path (list): Full paths to triangulated files for analysis, or a directory containing them.
80+
videofolder (string): Full path of the folder where videos are stored.
81+
Use when videos are not co-located with triangulation files.
82+
Defaults to None (videos searched next to the triangulation file).
83+
start (int): Start frame index to select. Defaults to 0.
84+
end (int): End frame index to select.
85+
Defaults to None (all frames used).
86+
trailpoints (int): Number of previous frames whose body parts are plotted (history).
87+
Defaults to 0.
88+
videotype (string, optional): When ``path`` is a directory, only videos with this extension are
89+
analyzed. If unspecified, common extensions ('avi', 'mp4', 'mov', 'mpeg', 'mkv') are kept.
90+
view (list): Elevation (z plane) and azimuth (x,y plane) angles for the 3D view.
91+
xlim (list): Limits for the 3D x-axis.
92+
Defaults to [None, None] (min/max over all bodyparts).
93+
ylim (list): Limits for the 3D y-axis.
94+
Defaults to [None, None] (min/max over all bodyparts).
95+
zlim (list): Limits for the 3D z-axis.
96+
Defaults to [None, None] (min/max over all bodyparts).
97+
draw_skeleton (bool): If True, draw skeleton lines on each frame (from config).
98+
Defaults to True.
99+
color_by (string, optional): Coloring rule. Each bodypart colored differently by default.
100+
Use 'individual' to color all points of one individual the same. Defaults to 'bodypart'.
101+
102+
Examples:
103+
Linux/MacOs
104+
>>> deeplabcut.create_labeled_video_3d(config, ["/data/project1/videos/3d.h5"], start=100, end=500)
105+
106+
To create labeled videos for all the triangulated files in the folder
107+
>>> deeplabcut.create_labeled_video_3d(config, ["/data/project1/videos"], start=100, end=500)
108+
109+
To set the xlim, ylim, zlim and rotate the view of the 3d axis
110+
>>> deeplabcut.create_labeled_video_3d(config,['/data/project1/videos'],start=100,
149111
end=500,view=[30,90],xlim=[-12,12],ylim=[15,25],zlim=[20,30])
150112
"""
151113
os.getcwd()

0 commit comments

Comments
 (0)