XManager: Using the Subject Populator

The Subject Populator is a utility in xManager that fills out the items in a subject file, based on data files that it finds in a folder that you specify. It can be helpful when you are starting a new study and need to create a subject file with all the appropriate sessions, trackable objects, configurations, and trials. If all of the subjects in your study have the same trials, then you can use a subject template for creating subsequent subject files. However, if the trials differ from subject to subject, you can use the Subject Populator to fill out the subject file for each one.

To use this utility, follow these steps:

1. Create a new subject file in xManager and add the sessions that you want populated. You do not need to add any configurations or trials.
2. Add the trackable objects to each session. You only need to specify the name of each object; xManager will fill in the image file and surface files if they are found in the right folder.
3. Select File → Populate From Data Folder. You will be prompted to select the top-level folder containing the subject data. xManager will scan the contents and guess which subfolders contain which files, and what the view names and other keywords are. It will then display a dialog with all of these guesses.
4. Check all of the items in the dialog, changing any of them that are missing or incorrect. The subject components are divided into three sections (configurations/trials, objects, and scan data) and you can unselect any section to skip processing that group of files. Each item has pop-up text describing how it is used.
5. Press OK to populate the subject file.

This utility is designed to work with a top-level folder (e.g., Subject01) that contains subfolders for the trial data (e.g., Subject01/Trials) and trackable objects (e.g., Subject01/Bones). If the subject contains multiple sessions, then each session’s data must be in a subfolder with the name of the session (e.g., Subject01/Session1/Trials, Subject01/Session2/Bones). Exception: If there are multiple sessions and there is trackable object data in a folder such as Subject01/Bones, it will be added to every session in the subject. If you have trackable object data for individual sessions, then put it in the session folders (e.g., Subject01/Session2/Bones).

Scan data works similarly to trackable object data, in that it can be put in session folders or in the top-level subject folder. The difference is that you can have separate folders for CT and MRI (e.g., Subject01/CT, Subject01/MRI, Subject01/Session1/CT, Subject02/Session2/MRI). However, both CT and MRI data end up in the same place (in the Scan Data section for the session). Each folder of scan data should contain DICOM images that have the same size, spacing, and orientation. For example, if in a knee study you have slices at the hip and ankle for determining joint centers, then the files should be divided into three folders (e.g., Subject01/CT/hip, Subject01/CT/knee, Subject01/CT/ankle). None of these folders should contain scout scans or other extraneous files.

In the main folder for each session’s X-ray trial data (e.g., Subject01/Trials) xManager expects each subfolder to be the name of a configuration (e.g., Subject01/Trials/Config1). All X-ray files for this configuration must be in this folder, including those for the calibration trials. xManager will assume that all files in this folder that are of the specified type (cine or tif) are uncorrected X-ray files. No corrected files will be added to the subject file.

If your X-ray files use the standard Phantom naming convention (<trial>_Cam_<camera>_Cine1.cine), xManager will be able to extract the trial names and view (camera) names from them. If they do not use this format, they must use the following format: <trial>_<view>.cine (or .tif).

If you will be using Surface3D to segment the scan data and create image and surface files for the trackable objects, then when you are populating the subject file there will probably not yet be any object files to process. If there are, whether you created them earlier in Surface3D or in a third-party program, they must be in a folder with the name of the object (e.g., Subject01/Bones/Femur_R, Subject01/Bones/Tibia_R) and every object file must contain the name of the object (case-sensitive). xManager will process segmented image files, surface files, ROI surface files, and inner surface files, if you specify the appropriate key phrases in the dialog. For segmented image files in the raw format, xManager will extract the dimensions and voxel size from the file name, assuming that the dimensions are immediately followed by the voxel size, with all six values separated by underscores. You can also put items like "16bit" and "LE" (little-endian) in the file name and xManager will extract them. Bit-depth is not necessary, though, because xManager will calculate it from the dimensions and the file size. For example, with this file name: Femur_R_283_221_180_3125_3125_5_LE.raw the extracted image dimensions will be 283x221x180 voxels, with a voxel size of 0.3125x0.3125x0.5 mm and using the little-endian format.

It is recommended that you select the Use Relative Path Shortcuts option. If selected, when xManager adds a path shortcut to the subject file (e.g., shortcut to the X-ray folder, to the objects folder), the path will be relative to the folder containing the subject file. Making all path shortcuts relative to the subject file makes it easier to move the data folder to another location on your computer or to another computer. However, this is not practical if some of the data must be kept on a shared network drive.

The Overwrite Existing File Paths option can be used if the subject file already contains links to data files and you want to overwrite them with ones generated by the Subject Populator. This option will not clear out the sessions, configurations, views, trials, and objects from the subject file and start over; it will only add new items or overwrite existing ones as dictated by the files it discovers. If the subject file already contains views that do not match the names you specify in the dialog, you will get undesirable results.