Tracks the movement of cells from a video source. Currently the code has only been verified to work in 2D, with bacteria-shaped cells. More to come. Our first paper can be found at https://www.mdpi.com/1999-4893/15/2/51, and the PDF is available is available in the top directory of the repo.
Once you clone the repo onto your machine, you should test if Cell Universe is working on your system by installing the requirements and running the script ./regression-test-all.sh.
Requires Python 3.11+.
Recommendations
Requires Pip. https://pip.pypa.io/en/stable/quickstart/
Quickstart:
- Install Pipenv
$ pip install pipenv- Install required packages using Pipenv
$ pipenv installThis will create a virtual environment with all the required Python packages
- Activate Pipenv environment
$ pipenv shell- Separate your video into still images, one image per frame and put them in a directory with chronological names like
frame000.png,frame001.png, etc. - Cell Universe needs a starting "guess" for the number, location, size, and orientation of the cells in the first frame. You can do this visually using the cell labeling tool Python program. This will create an initial properties file with all that information. See the
tools/cell_labeling_tool/README.mdfor more information about the cell labeling tool andexamples/canonical/initial.csvfor an example initial properties file generated by the cell labeling tool.
(venv)$ python3 tools/cell_labeling_tool/cell_labeling_tool.py- Create a Cell Universe config file and fill it in with settings that fits your cell video. See
examples/canonical/global_optimizer_config.json(and the comments in the file) and other config JSON files in theexamplesdirectory for examples.- It is important to change settings in the config file like the "Global Setttings" and the "Bacilli Settings" to match your cell video, or else Cell Universe will not function properly.
- Run Cell Universe, giving it the input directory containing the frames, the initial properties file created above, the config file, as well as the other required arguments (see in the Usage section).
- An example command is at the bottom of this README and more in the
run.shscript files in theexamplesdirectory.
- An example command is at the bottom of this README and more in the
There are several examples in subdirectories below the directory regression-tests and examples.
Command line help:
usage: main.py [-h] [-d DIRECTORY] [-ff N] [-lf N] [--dist] [-w WORKERS] [-j JOBS] [--keep KEEP]
[--strategy STRATEGY] [--cluster CLUSTER] [--no_parallel] [--global_optimization]
[--binary] [--graySynthetic] [--phaseContrast] [-ta TEMP] [-ts START_TEMP]
[-te END_TEMP] [-am {none,frame,factor,const,cost}] [-r FILE] [--lineage_file FILE]
[--continue_from N] [--seed N] [--batches N] -i PATTERN -o DIRECTORY -c FILE -x FILE -b FILE
optional arguments:
-h, --help show this help message and exit
-d DIRECTORY, --debug DIRECTORY
path to the debug directory (enables debug mode)
-ff N, --frame_first N
starting image (default: 0)
-lf N, --frame_last N
final image (defaults to until last image)
--dist use distance-based objective function
-w WORKERS, --workers WORKERS
number of parallel workers (defaults to number of
processors)
-j JOBS, --jobs JOBS number of jobs per frame (defaults to --workers/-w)
--keep KEEP number of top solutions kept (must be equal or less
than --jobs/-j)
--strategy STRATEGY one of "best-wins", "worst-wins", "extreme-wins"
--cluster CLUSTER dask cluster address (defaults to local cluster)
--no_parallel disable parallelism
--global_optimization
global optimization
--binary input image is binary
--graySynthetic enables the use of the grayscale synthetic image for
use with non-thresholded images
--phaseContrast enables the use of the grayscale synthetic image for
phase contract images
-ta TEMP, --auto_temp TEMP
auto temperature scheduling for the simulated
annealing
-ts START_TEMP, --start_temp START_TEMP
starting temperature for the simulated annealing
-te END_TEMP, --end_temp END_TEMP
ending temperature for the simulated annealing
-am {none,frame,factor,const,cost}, --auto_meth {none,frame,factor,const,cost}
method for auto-temperature scheduling
-r FILE, --residual FILE
path to the residual image output directory
--lineage_file FILE path to previous lineage file
--continue_from N load already found orientation of cells and start from
the continue_from frame
--seed N seed for random number generation
--batches N number of batches to split each frame into for
multithreading
required arguments:
-i PATTERN, --input PATTERN
input filename pattern (e.g. "image%03d.png")
-o DIRECTORY, --output DIRECTORY
path to the output directory
-c FILE, --config FILE
path to the configuration file
-x FILE, --initial FILE
path to the initial cell configuration
-b FILE, --bestfit FILE
path to the best fit synthetic image output directory
python3 src/main.py --frame_first 0 --frame_last 13 --input "./examples/canonical/input/gray/frame%03d.png" \
--output "./examples/canonical/output" --bestfit "./examples/canonical/output/bestfit" --config \
"./examples/canonical/global_optimizer_config.json" --initial "./examples/canonical/initial.csv" --no_parallel \
--graySynthetic --global_optimization
There are currently four running examples located in the example folders. Each example is packed into a folder, which consists the input images, the initial cell configuration file, the configuration files, and the scripts to run the example. The scripts doesn't do anything magic. It's simply a wrapper of the command to run the program.
To run the examples:
Step 1: Activate the python environment. To do this, first locate to the root directory of this project, and run
pipenv shell
Step 2: Move to the folder consists the example that you want to run. Here, use the canonical one as an example.
cd examples/canonical
Step 3: Use the script to run the example
For Windows Users (Powershell):
.\run.ps1
For Linux Users (Bash):
.\run.sh
Step 4: Wait until the program finish. The output is located in the output folder in the example folder.