DLTdv8 online manual

This is the online manual for DLTdv8, last updated 2025-09-06. At the moment this consists mostly of a series of tutorial videos (below). To follow along with the tutorial you’ll need the DLTdv8_tutorial_data.zip file. If you want to test out using trained Deep Learning networks with DLTdv8 but can’t or don’t want to train them yourself you can download pre-trained tutorial networks and import them using the Network Manager while following along with the tutorial. Many of the older tutorials for DLTdv versions prior to version 8 are still relevant, you can find these on the main DLTdv landing page https://biomech.web.unc.edu/dltdv/

Menu commands

Project

New – active only when DLTdv is first started, creates a new project beginning with video selection

Load – active only when DLTdv is first started, load a previously saved project

Save – save the current project as a MATLAB MAT file that can later be loaded with the “Load” command

Save as – save the current project as a MATLAB MAT file under a new name

Export to workspace – pushes the data contents of the DLTdv8 app to the main MATLAB workspace

Quit – quits DLTdv

Points

Export – save the current 2D and 3D points as text files, either comma-separated spreadsheet format (i.e. flat format) or tab-separated sparse array format

Load – loads 2D and 3D points from text files in either of the Export formats. Useful for pulling data in from other programs

Flip vertical – “flips” the vertical coordinate in all digitized points. This is useful because DLTdv versions prior to DLTdv8 put the pixel coordinate origin in the lower left corner of the image; DLTdv8 moves it to the computer vision standard location of the upper left corner. If you import points from DLTdv7 or earlier into DLTdv8 you should then do the “flip vertical” operation

Metadata editor – brings up a separate interface panel for setting point names, adding and deleting points, reordering them, etc.

3D

Load new DLT coefficients – Brings up a dialogue to load a new set of DLT coefficients; the DLT coefficients encode the position and orientation of the cameras in 3D space as well as their lens properties, so loading new coefficients means changing the 2D –> 3D calibration

Recompute 3D points – Forces DLTdv to recompute all 3D coordinates from the current 2D coordinates and DLT coefficients. It is possible (although unlikely) for the 3D coordinates to get out of sync with the 2D coordinates, especially if you have re-created a project by loading exported points.

Flip DLT coefficients – “Flips” the DLT coefficients such that coefficients from DLTdv7 and earlier will work with DLTdv8. DLTdv8 puts the image coordinate system in the upper left corner for better compatibility with computer vision workflows; DLTdv7 and earlier used the lower left corner.

Deep Learning

Manage datastores – brings up the datastore management sub-interface where you can create/import/export and otherwise manage datastores. Datastores are snapshots of all or part of a combined digitized point set and video and are used for training Deep Learning neural networks.

Manage networks – brings up the deep learning network management sub-interface where you can create/import/export/train deep learning networks using datastores created as part of the current project or imported from other projects.

Apply network – brings up the deep learning application sub-interface where you can use deep learning networks to find landmarks in one or more of the videos in this project.

Check graphics card – checks for a CUDA enabled graphics card. If none is found it will report that no GPU is detected, otherwise it will report the specifications for the card.

Utilities

Start calibration tool – Starts the DLTcal8 interface, a reduced form of the DLTdv interface optimized for computing 2D or 3D DLT coefficients from manually identified image points (i.e. pixel coordinates) and a set of known 2D 3D points, i.e. a calibration frame.

Set 2D scale and origin – Starts the scale and origin interface, which lets you set the coordinate system origin and image scale if you’re working with a single video and have not loaded an 2D DLT coefficients. This operation actually creates a set of 2D DLT coefficients which can then be exported for use on identically scaled videos.

Export DLT coefficients – Saves the current set of DLT coefficients to a file

Help

List of mouse and keyboard commands – brings up a separate window with a formatted list of all the mouse and keyboard commands available in DLTdv

Open online manual – opens this page in a web browser

Version – displays the DLTdv8 version

Check for a new version – checks to see if you’re using the latest version by comparing the internal version number to a file on http://hedricklab.bio.unc.edu

License – displays the license information for DLTdv8 (the BSD 3-clause open source license). Note that “compiled” MATLAB packages are not compatible with the GPL since the binary distribution does not include all the source code necessary, e.g. the source code for MATLAB itself.

Camera calibration options and DLT coefficients

As the name suggests, DLTdv8 is built around the DLT or Direct Linear Transformation method of camera calibration. In the general sense, camera calibration could be thought of as a process or method for determining the imaging properties of a camera, in the case of DLTdv8 this is with an eye toward making dimensional measurements of objects or movements seen by the cameras. DLT comes in 3D and 2D flavors; 3D DLT is a pinhole camera model formulation and as such includes the intrinsic and extrinsic parameters that respectively describe the camera and its position and orientation in the scene. These can be extracted from the DLT coefficients and vice versa, see https://biomech.web.unc.edu/dlt-to-from-intrinsic-extrinsic/. DLT coefficients are specific to each individual camera, and the information in the 3D DLT coefficients plus the observed pixel or image coordinates of an object seen in two calibrated cameras is sufficient to calculate the object’s 3D location. DLT coefficients can be computed in many ways, DLTdv8 includes the DLTcal8 tool for computing 3D DLT coefficients from 1) a file specifying the X-Y-Z location of at least 6 but preferably more locations or markers and 2) the pixel coordinates of these locations, marked using the DLTcal8 tool. This method usually described as calibration using a calibration frame, where the frame is an object with the 6+ known 3D locations. It’s uncommon in the computer vision literature, but of great use in laboratory experiments because the method is quick, precise, and easily recreated over many recording days. The Hedrick lab wand calibration tools easyWand and simpleWand provide an alternate means for getting DLT coefficients when constructing and placing a calibration frame is not feasible, and other calibration methods that produce pinhole camera intrinsic+extrinsic outputs can also be converted to DLT for use with DLTdv.

Two dimensional DLT, or 2D DLT is a reduced camera model that corrects for a perspective or oblique view of a 2D surface or plane, mapping a pixel [u,v] coordinate to a dimensional [X,Y] coordinate. Because the input from a single camera provides the needed two degrees of freedom in the output, so a single camera is all that is needed for 2D DLT. However, the approach can also be extended to more than one camera, allowing broader coverage of a scene and error estimates for measurements of objects seen by 2+ cameras. DLTcal8 can compute 2D DLT coefficients; if the calibration frame has only two columns ([X,Y]) instead of three ([X,Y,Z]) then it shifts into 2D mode. 2D DLT calibration requires a minimum of 4 calibration frame points and can incorporate additional points to get a more robust fit and an error estimate.

If a project is started with only one camera and no 2D DLT coefficients then DLTdv8 can set a simple origin and pixel scale. Internally, this is implemented as a 2D DLT computation, so the resulting coefficients can be saved out and used elsewhere in identically-scaled images. See the Utilities menu, Set 2D scale and origin option.

Lens distortion

Many real-world cameras have some degree of lens distortion, though not always enough to affect measurement results. DLTdv8 handles lens distortion through a generalized image transform mechanism (image tform) that can in principle accommodate the common radial + tangential lens distortion models, more unusual formulations such as fisheye distortion, and even more complex situations such as lens distortion + refraction through a water surface. The transforms are stored in a separate MATLAB data file, one per camera. The simpleWand and easyWand calibration methods estimate the radial + tangential distortion model and create the MATLAB files, using a naming convention that lets DLTdv8 find and load them along with the associated DLT coefficients. DLTdv8 can also load a radial+tangential distortion camera profile stored as text in the simpleWand format and create the transform internally. Frame based calibration using DLTcal8 does not support accounting for lens distortion at this time, so if you think lens distortion might be a problem you should choose some other calibration method.

Tips for working with the “compiled” DLTdv8

2025-06-18 Note: the “compiled” DLTdv8 has not been re-created for a while and is out of date compared to the current app version. I hope to address this in summer 2025.

The compiled version of DLTdv8 uses the MATLAB runtime, a sort of hidden MATLAB install that does not allow direct user interaction but can run specific MATLAB programs such as DLTdv8. Unfortunately, on MacOS the MATLAB runtime does not create a display window to show any of the messages or errors that would normally appear on the MATLAB console. If you find the DLTdv8.app icon and click on it you’ll start DLTdv8, but won’t be able to see some informational messages, especially those related to deep learning network training. However, if you start DLTdv8 using the MacOS Terminal, the messages will appear there. Here’s how:

start Terminal, input the following command and press enter:

/Applications/DLTdv8a/application/run_DLTdv8a.sh /Applications/MATLAB/MATLAB_Runtime/v97/

Video Tutorials

Due to changes in the UNC campus IT infrastructure, video tutorials now open in a new tab using the Panopto video player which does not permit you to download them from offline use. Please email me if you’d like access to the raw video, or if Panopto is not permitting access.

2D (pixel coordinate) and 3D tracking

Interactively tracking a point with a deep learning network

Tracking multiple points with a deep learning network

Tracking multiple points in multiple videos with a deep learning network

Re-training a network with data from multiple videos

2D DLT calibration and tracking [sample data for this tutorial]

Contents: