DeepCell Label is a web-based data annotation tool based on Flask and can be run locally or deployed to the cloud (e.g. AWS Elastic Beanstalk).
For an up-to-date list of features, see the Controls section.
Using a virtual environment to install dependencies is recommended.
pip install -r requirements.txtpython3 application.pyAdd your AWS credentials to docker-compose.yaml or set them via the environment.
From the root directory, run:
sudo docker-compose up --build -dWait a minute for the database to finish setting up before running:
sudo docker-compose restart appYou can now go to 0.0.0.0:5000 in a browser window to access the local version of the tool.
To interact with the local mysql database:
sudo docker exec -it browser_db_1 bash
mysql -pWhen finished:
sudo docker-compose down(optional)
sudo docker system prune --volumesFlask is used as an HTTP server that serves the frames as pngs and metadata as JSON. The .js files in the deepcell_label/template folder are what makes the requests to the Flask server.
Python Flask was used as a web application framework for constructing DeepCell Label. The Flask framework helps serves as the router that maps the specific URL with the associated function that is intended to perform some task. Specifically, the application.route decorator binds the URL rule to the function below it. Thus, if user performs actions that cause a change in the underlying data, the side-serving .js file will request to visits a specific URL, and the output of the function below the decorator will be rendered in the browser.
Functions depend on Python libraries -- including NumPy, Matplotlib, and scikit-image – to change the data within files. After the desired change has been made to the lineage information or mask annotation, the Flask app routing will update the interface to reflect the alterations with support from side-serving JavaScript scripts.
The final Flask application has been deployed to an AWS Elastic Beanstalk environment as a RESTful web service. A stable demo of the browser application can be accessed at label.deepcell.org. To deploy this application to AWS EB, an AWS RDS MySQL database must be set up and configured to handle data storage for application use. (Add database credentials to the .env configuration file.) Once a database is appropriately configured, the application can easily be launched by using the AWS EB command line tool or web interface. The .ebextensions folder will configure the web service to use the appropriate Flask application (eb_application.py, which uses a MySQL database instead of SQLite).
DeepCell Label can also be run locally using a SQLite database (this is the default behavior). When we start using DeepCell Label, DeepCell Label creates a project with a unique 12 character ID, and stores it locally in /tmp/deepcell_label.db. Whenever we edit the project, DeepCell Label updates the object in the database. Running application.py creates the database if it does not already exist.
Label shows an Info Table on the left with project details and an interactive Canvas on the right that shows images and labels.
The infopane is a table with information about the project,
The first three rows in the table tell us the which slice in an image stack we are currently viewing
- frame tells which slice of an image stack we are viewing
- Frames move through space (like a 3D vertical image stack) or through time (like a timelapse)
- channel tells us which raw image channel we are viewing
- Channels may be different imaging modalities, like phase or fluorescence, or different markers, like nuclear or cytoplasm
- feature tells us which labeled features we are viewing
- Features may be [FILL IN]
The next three rows tell us where the canvas is within the current frame.
- zoom tells us how much the frame is zoomed in
- viewing (x) the visible horizontal range
- viewing (y) the visible vertical range
These two rows tell us about visual settings
- highlight tells us whether the label we're painting with is highlighted in red
- brush size tells us the radius of the brush in pixels
The next two rows tell us about the label the mouse is hovering over
- label is the label number under the mouse
- slices is a list of the frames that the label is present in
The next two rows tell us which labels we can edit with the brush tool
- painting with label is the label the we brush adds to the canvas
- painting over label is the label the brush overwrites
The last two rows are about label editing actions
- tool tells us what action happens when we click on the canvas
- See the Tools section for more details
- confirm action is a prompt displayed before some actions
- We can confirm the action with Enter, or cancel it with Esc. See the Actions section for more details.
These controls are also found in the dropdown "instructions" pane while editing a file.
Hover the mouse over a label to view the label info.
Press + or hold Alt and scroll up to zoom in.
Press + or hold Alt and scroll down to zoom out.
Hold Space and move the mouse on the canvas to pan around.
Press D or → to view the next frame.
Press A or ← to view the previous frame.
Press C to view the next channel.
Press Shift + C to view the previous channel.
Press F to view the next feature.
Press Shift + F to view the previous feature.
DeepCell Label can adjust how to display labels and images. With these changes, we can make out finer details while labeling.
Scroll on the canvas to change brightness.
Hold Shift and scroll on the canvas to change the contrast.
Press 0 (zero) to reset the brightness and contrast.
Press Z to toggle between viewing the label overlay, the labels only, and the raw image only.
Press H to toggle highlighting the brush label in red.
We control which labels we cab edit by selecting them as the foreground or the background.
When a label is the foreground, we can add more of that label, while when a label is background, we can remove it.
You select "no label" as either the foreground, which lets us remove existing labels, or the background, which lets us labels over unlabeled areas.
We can select a label as the foreground in two ways:
Click on it while using the Select Tool
Shift + Double Click while using any Tool.
We can select a label as the background in two ways:
Double Click on it while using the Select Tool.
Shift + Click while using any Tool.
Double clicking also deselects other labels, instead making "no label" the other selected label. This helps avoid having selected labels that you are no longer working on.
When you select an label that is already selected, the foreground and background swap instead.
Use this as a shortcut when working on a pair of labels, like adjusting their boundary so you can quickly work in both directions.
Here are some keyboard shortcuts to change the selected labels.
- Press Esc to reset the background to "no label".
- Press N to select a new, unused foreground label.
- This will be a label that doesn't exist yet in the labeling. Once you add the new label, N will select a new, even higher label.
- Press X to swap the foreground and background. Remember that you can also swap them by selecting either label a second time with the mouse.
- Press [ or ] to cycle the foreground labels.
- Press Shift + [ or Shift + ] to cycle the background labels.
Each tool lets us edit the labeling in a different way. To edit the labels with a tool, click on canvas while using the tool.
Label starts with the Select tool by default, which selects the foreground and the background label.
Press V to use the Select tool.
Click on a label to select it as the foreground,
Double Click on a label to select it as the background.
You can also select labels while using any tool with Shift + Click to select the background, or Shift + Double Click to select the foreground.
Double Click to select also deselects other labels.
The Brush tool paints the foreground label over the background label. Other labels are left unedited.
Press B to use the Brush tool.
Click + Drag to paint.
Press ↑ to increase the brush size. Press ↓ to decrease the brush size.
The Threshold tool fills the brightest pixels within a bounding box with the foreground label. The tool only overwrites unlabeled area and does not edit any other labels.
Press T to use the Threshold tool.
Click + Drag on the canvas to draw a bounding box and threshold.
The Grow/Shrink tool expands the foreground label by one pixel or contracts the background label by one pixel.
Press Q to use the Grow/Shrink tool.
Click on the foreground label to grow it.
Click on the background label to shrink it.
The Flood tool fills connected areas of label with another label.
Press G to use the Flood tool.
Click on the background label to flood it with the foreground label.
The Trim tool removes disconnected areas of the background label, leaving only the connected pixels behind.
Press K to use the Trim tool.
Click on the background label to trim it.
The Autofit tool adjusts foreground label boundary to hug the nearest edges in the raw image. This tool helps to fix the boundaries of an existing label, but it can't add a new label from scratch.
Press M to use the Autofit tool.
Click on the foreground label to autofit it.
The Watershed tool splits the foreground label into two. We can separate adjacent cells that mistakenly have the same label with Watershed.
Press the W to use the Watershed tool.
Click in the center of one cell, then Click in the center of another cell elsewhere in the same label to split them with Watershed.
Tools like Autofit or Flood can only edit selected labels.
To make these tools easier to use, clicking on an unselected label with these tools selects the label instead of doing an action. After clicking once to select, a second click on the same label always uses the tool and edits the labels.
The Grow/Shrink, Autofit, and Watershed tools makes unselect labels the foreground.
The Trim and Flood tools makes unselected labels the background.
Actions edit labels with a keybind. Actions need to be confirmed with Enter or cancelled with Escape.
Press S to swap the label foreground and background labels. This action can only swap the labels on the current frame.
Press R to replace the background label with the foreground label. Press Shift + R to replace the background label on all frames.
Press O to predict the labels based on the overlap with the previous frame. Press Shift + O to predict the labels on all frames.