diff --git a/_pages/plugins/trackmate/tutorials/trackmate-segmentation-editor.md b/_pages/plugins/trackmate/tutorials/trackmate-segmentation-editor.md index dceedc0f1..5acc7c9f0 100644 --- a/_pages/plugins/trackmate/tutorials/trackmate-segmentation-editor.md +++ b/_pages/plugins/trackmate/tutorials/trackmate-segmentation-editor.md @@ -6,68 +6,38 @@ artifact: sc.fiji:TrackMate section: Tips and Tricks:Closing the editor window --- - Since version 8, TrackMate ships a new feature that allows editing object shape in 2D. The spot editor is based on [Labkit](/plugins/labkit) components, and is made to simplify and accelerate the creation of tracking ground truth. -In this tutorial we will explain how to use it to modify segmentation results directly in TrackMate - -## Preparing the tutorial data - -Download [this image](/media/plugins/trackmate/spot-editor/Celegans-2D.tif) and open it in Fiji. -It is a movie of the early development of a _C. elegans_ embryo, projected in 2D, for which the nuclei have been stained in fluorescence. -We will generate an incorrect segmentation of these nuclei in TrackMate, and fix it with the spot editor. - -In Fiji, with the image open, launch TrackMate ({% include bc path="Plugins|Tracking|TrackMate"%}). -Click the _Next_ button and select the _Thresholding detector_. -In its configuration page, put a threshold of 1000 and click _Next_. - -{% include img src="/media/plugins/trackmate/spot-editor/trackmate-spot-editor-tuto-02.png" align="center" width="300px" %} - -Click the _Next_ button until you are in the tracker selection page and select the _LAP tracker_. -In its configuration page, -- put 5 µm as max linking distance, -- uncheck the _Track segment gap closing_ button, -- check the _Track segment splitting_ button and put a _max distance_ of 5 µm, -- uncheck everything else. - -You should get the following: +In this page we explain how to use it to modify segmentation results directly in TrackMate. -{% include img src="/media/plugins/trackmate/spot-editor/trackmate-spot-editor-tuto-03.png" align="center" width="300px" %} +## The editor -## Launching the spot editor - -The threshold we set is too stringent, and many nuclei are improperly segmented, and some polar bodies are missing. -For instance, in frame 2 the top-left nucleus looks like this: - -{% include img src="/media/plugins/trackmate/spot-editor/trackmate-spot-editor-tuto-05.png" align="center" width="300px" %} - -We will use the spot editor to correct some of the mistakes there. The spot editor can be launched from the _Display options_ panel of TrackMate: {% include img src="/media/plugins/trackmate/spot-editor/trackmate-spot-editor-tuto-04.png" align="center" %} -Move to frame 2 and click the `Launch spot editor button`. -The user interface of TrackMate is frozen and a new window appear: +This button is visible only for 2D images. +When clicking on this button, the user interface of TrackMate is frozen and a new window appear: {% include img src="/media/plugins/trackmate/spot-editor/trackmate-spot-editor-tuto-06.png" align="center" %} -The large bottom right panel displays the image overlaid with the spots. -Notice that the spots have been converted to masks, and that they have the same color that in the TrackMate UI. +The editor is made of several UI components: +- The main editor panel, where the image is painted along with the spot masks (center). +- The side panel (left) that contains from top to bottom: + - the 'Close and sen' button, that finishes editing and returns to TrackMate; + - the image visibility tool (with the eye button), that let you hide / unhide the image, perform auto contrast, and open the display settings panel (will appear on the right); + - the spot label list, listing all spots currently in the editor, and a global visibility button (the eye). +- The toolbar (top). -The top bar is made of widgets that change the brush mode (navigate, add, remove, fill, ...) and the brush size. -We will describe them below. +The toolbar shows the six editing tool we use to annotate an image: -The left side bar contains (from top to bottom) -- the button to end editing, -- auto-contrast and display config panel for the spot editor, -- the list of labels currently in the editor, initially there is one label per spot, -- a button to create a new label, possibly for a new spot. +{% include img src="/media/plugins/trackmate/spot-editor/trackmate-spot-editor-six-tools-annotation-bis.png" align="center" %} ## Navigating in the editor The editor window is actually a [BDV component](/plugins/bdv/index). If you know your way around BDV you will get your bearings quickly. -Otherwise here is how to navigate in the image panel. +Otherwise, here is how to navigate in the image panel. ### Panning, rotating and zooming @@ -87,6 +57,8 @@ Otherwise here is how to navigate in the image panel. ### Navigating to spots On the left side bar, you can see the list of labels currently in the editor. +Each label initially corresponds to a spot in TrackMate. +The label will have the same name and color that of the current view in TrackMate. Shift-clicking on a label in the list will center the image view on the corresponding spot mask {% include img src="/media/plugins/trackmate/spot-editor/trackmate-spot-editor-tuto-09.gif" align="center" %} @@ -101,57 +73,142 @@ The _settings_ button will open a dialog to change the display settings of the i ## Editing spots -Let's fix the top left nucleus in frame 2. -Center and zoom in on it, so that it fills the panel. -We see that there are two spurious detections on the side, of 1-pixel size, and that the largest spot is not large enough to cover the nucleus. -Let's first remove the spurious detections. +Editing spots is made by painting labels in the editor. +When you modify a label, the modifications will be reimported into TrackMate when you close the editor. +In TrackMate, 2D spots are polygons, but we found out that painting inside the input image then converting to spots was fast and convenient, particularly with a tablet. + +### For editing, TrackMate spots are written into labels + +The editor will display the spots as a 'labeling', a colored image where the pixels inside each spot is painted with a specific label. +All the labels corresponding to the spots in the image are listed on the left side bar. +The are created with the same color and name that of the spot they correspond to. + +So it is possible that two different spots will lead to two different labels in the editor, but with the same color, which will make them indisinguishable. +If this is the case we recommend changing the spot coloring before launching the editor. +For instance, selecting the _Random color_ mode. + +{% include img src="/media/plugins/trackmate/spot-editor/TrackMate-Editor-RandomColoring.png" align="center" width="300" %} + +Modifying a spot is adding a removing pixels from its shape. +There is a gotcha however: When you finish editing the actual label of a spot does not matter anymore. +For instance, if you paint a new spot with an existing label, so that the new spot is disconnected from the initial spot or even on another time-point, the new spot will be created as a separated one in TrackMate. +The fact that the initial spot and the new one have the same label plays no role if they are not touching. + +### The six editing tools + +When you select one of the tool by cliking on its icon or with F1 - F6, the right part of the toolbar changes to show the tool controls. + +### The pan / move tool - {% include key key="F1" %} + +See above. +When this tool is selected, the mouse is used to navigate in the image. + +### Painting labels - {% include key key="F2" %} + +When the paint tool is selected, left clicking in the image will paint the label currently selected in the image, as if you had a brush. +You can select a label in the side bar, or create a new label to create a new spot. +The select label tool described below is used to select a label at a given pixel. + +You can change the diameter of the brush with the slider that appears right of the toolbar. +The default key shortcuts to do so are {% include key key="Q" %} / {% include key key="E" %} and {% include key key="Shift|Q" %} / {% include key key="Shift|E" %} + +The rightmost list allows changing the paint mode. +There are three of them: _Replace, Add, Preserve_. +The selected modes and brush size are remembered between use of the editor. + +#### Paint replace + +This is the default mode. +If you paint over an existing label, it is discarded. -### Deleting pixels +{% include img src="/media/plugins/trackmate/spot-editor/TrackMate-Editor-Paint-Replace.gif" align="center" %} -The fourth button on the top bar is the _Delete_ button. -Click it to make the delete brush mode active. -But if you click on the spurious detections, nothing happens. -This is because the **delete brush only works on the pixels of the label that is currently selected in the left side bar**. -You need to select the label you want to edit first. -To do so, you can either -- {% include key key="Shift|left click" %} on the spot mask in the image panel, -- click on the _Select_ button on the top toolbar (the sixth button on the left) then click on the spot in the image, -- or select the label in the left side bar. +#### Paint add -{% include notice icon="note" - content="*Shift-click* in the image selects the spot at the cursor position." %} +In TrackMate the spots can be overlapping, and as a consequence, in the editor you can have several labels on one pixel. +This is the way to edit overlapping spots. +The _Add_ mode paint labels, and if there is an existing label, it will add the selected one, and not remove the existing one: -{% include img src="/media/plugins/trackmate/spot-editor/trackmate-spot-editor-tuto-11.gif" align="center" %} +{% include img src="/media/plugins/trackmate/spot-editor/TrackMate-Editor-Paint-AddMode.gif" align="center" %} -Shift-click on each of the spurious detections to select them, and then click on them with the _delete_ brush on to remove them. -Notice that the corresponding labels in the left side bar are not removed, which is normal. +This will lead to overlapping spots, as demonstrated in the animation above. -{% include img src="/media/plugins/trackmate/spot-editor/trackmate-spot-editor-tuto-12.gif" align="center" %} +#### Paint preserve -### Painting spots +This mode is the converse of the 'Replace' mode. +The selected label will be applied only on the pixels that have no label already. +It will only paint on the background. +This is useful if you have close objects that you know are not overlapping. -We now want to enlarge the largest spot to cover the nucleus. -First shift-click on it in the image panel to make the spot label active. -Then click on the _Add_ button in the top bar which is the second button from the left. -Edit the brush size to about 5 pixels, and paint over the nucleus. +{% include img src="/media/plugins/trackmate/spot-editor/TrackMate-Editor-Paint-PreserveMode.gif" align="center" %} -{% include img src="/media/plugins/trackmate/spot-editor/trackmate-spot-editor-tuto-13.gif" align="center" %} -### Removing entire spots +### Deleting pixels - {% include key key="F3" %} -You can also remove entire spots from the editor using the _Remove_ mode, which is the third button from the left in the top bar. -Again, the corresponding label of the spot to remove must be selected in the left side bar. -Click on the _Remove_ button, select the label in the left side bar and click on the spot you want to remove. +The delete tool also has several modes, that are made to harness possibly overlapping labels. -{% include img src="/media/plugins/trackmate/spot-editor/trackmate-spot-editor-tuto-14.gif" align="center" %} +#### Delete all labels -### Filling holes +This mode simply remove all labels at once. +You get the background where you paint. -Another way of creating spots is to paint the border and fill the inside. -After drawing the contour of the nucleus, you can use the _Fill_ button, which is the third button from the left in the top bar. -Click it, and click inside the contour to fill it. +{% include img src="/media/plugins/trackmate/spot-editor/TrackMate-Editor-Delete-AllLabels.gif" align="center" %} + +#### Delete selected label + +With this mode, the brush will only remove the label currently selected, and no touch the others: + +{% include img src="/media/plugins/trackmate/spot-editor/TrackMate-Editor-Delete-SelectedLabel.gif" align="center" %} + + +### Flood fill - {% include key key="F4" %} + +This tool allows for painting over a 'segment' of the labeling. +That is: any connected portion of the labels that have the same labels underneath. +It is most useful to replace a label or add one. +There is also two modes for this tool. + +#### Flood fill replace + +Similar to the _Paint add_ tool, this leads to replace all the label of a segment with the selected label. +On the animation below, the red part of the labeling is overwritten with the blue label, leading to a larger spot: + +{% include img src="/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodFill-Replace.gif" align="center" %} + +#### Flood fill add + +This _adds_ a label to a segment that might already have one. +On the animation below, the red label is added to the blue segment. +This segment has now two labels, the blue and the red, and it appers in magenta in the editor. +After returning to TrackMate, this leads to two spots overlapping: + +{% include img src="/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodFill-Add.gif" align="center" %} + +### Flood erase - {% include key key="F5" %} + +This tool removes one or all labels of a segment. + +#### Flood erase remove all + +All the labels are removed from the segment. +The modified pixels are now part of the background. + +{% include img src="/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodErase-RemoveAll.gif" align="center" %} + +#### Flood erase selected label + +Only the currently selected label is removed. +For instance, on the animation below, the top segment has two labels, red and blue, and appears in magenta. +The flood erase tool is used to remove the blue label from it, which leaves the red label. + +{% include img src="/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodErase-SelectedLabel.gif" align="center" %} + + +### Select label - {% include key key="F6" %} + +Click on any pixel to select its associated label. +If the pixel contains multiple labels, click repeatedly to cycle through them. -{% include img src="/media/plugins/trackmate/spot-editor/trackmate-spot-editor-tuto-15.gif" align="center" %} ### Keyboard shortcuts changing the brush mode and size @@ -219,8 +276,7 @@ This respects whether you have a ROI in the image or not. In TrackMate, spots are represented as polygons, as as such they can overlap. This is also the case in the spot editor. -This is the reason why it is necessary to select the spot you want to edit before using the brush. - +See the _Paint add_ mode above for instance. {% include img src="/media/plugins/trackmate/spot-editor/trackmate-spot-editor-tuto-22.gif" align="center" %} ### Several spots can have the same label @@ -251,4 +307,4 @@ Has the same effect as clicking the _Close and send to TrackMate_ button. ___ -Jean-Yves Tinevez, August 2025 +Jean-Yves Tinevez, August - December 2025 diff --git a/media/plugins/trackmate/spot-editor/TrackMate-Editor-Delete-AllLabels.gif b/media/plugins/trackmate/spot-editor/TrackMate-Editor-Delete-AllLabels.gif new file mode 100644 index 000000000..5f590120e Binary files /dev/null and b/media/plugins/trackmate/spot-editor/TrackMate-Editor-Delete-AllLabels.gif differ diff --git a/media/plugins/trackmate/spot-editor/TrackMate-Editor-Delete-SelectedLabel.gif b/media/plugins/trackmate/spot-editor/TrackMate-Editor-Delete-SelectedLabel.gif new file mode 100644 index 000000000..4dc876aef Binary files /dev/null and b/media/plugins/trackmate/spot-editor/TrackMate-Editor-Delete-SelectedLabel.gif differ diff --git a/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodErase-RemoveAll.gif b/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodErase-RemoveAll.gif new file mode 100644 index 000000000..43ad16d5e Binary files /dev/null and b/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodErase-RemoveAll.gif differ diff --git a/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodErase-SelectedLabel.gif b/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodErase-SelectedLabel.gif new file mode 100644 index 000000000..2b14c3c1b Binary files /dev/null and b/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodErase-SelectedLabel.gif differ diff --git a/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodFill-Add.gif b/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodFill-Add.gif new file mode 100644 index 000000000..a3ec0de16 Binary files /dev/null and b/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodFill-Add.gif differ diff --git a/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodFill-Replace.gif b/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodFill-Replace.gif new file mode 100644 index 000000000..858984af8 Binary files /dev/null and b/media/plugins/trackmate/spot-editor/TrackMate-Editor-FloodFill-Replace.gif differ diff --git a/media/plugins/trackmate/spot-editor/TrackMate-Editor-Paint-AddMode.gif b/media/plugins/trackmate/spot-editor/TrackMate-Editor-Paint-AddMode.gif new file mode 100644 index 000000000..5c171dc69 Binary files /dev/null and b/media/plugins/trackmate/spot-editor/TrackMate-Editor-Paint-AddMode.gif differ diff --git a/media/plugins/trackmate/spot-editor/TrackMate-Editor-Paint-PreserveMode.gif b/media/plugins/trackmate/spot-editor/TrackMate-Editor-Paint-PreserveMode.gif new file mode 100644 index 000000000..825e46a69 Binary files /dev/null and b/media/plugins/trackmate/spot-editor/TrackMate-Editor-Paint-PreserveMode.gif differ diff --git a/media/plugins/trackmate/spot-editor/TrackMate-Editor-Paint-Replace.gif b/media/plugins/trackmate/spot-editor/TrackMate-Editor-Paint-Replace.gif new file mode 100644 index 000000000..dbf280531 Binary files /dev/null and b/media/plugins/trackmate/spot-editor/TrackMate-Editor-Paint-Replace.gif differ diff --git a/media/plugins/trackmate/spot-editor/TrackMate-Editor-RandomColoring.png b/media/plugins/trackmate/spot-editor/TrackMate-Editor-RandomColoring.png new file mode 100644 index 000000000..6aa75b7c0 Binary files /dev/null and b/media/plugins/trackmate/spot-editor/TrackMate-Editor-RandomColoring.png differ diff --git a/media/plugins/trackmate/spot-editor/trackmate-spot-editor-alpha-transparency.png b/media/plugins/trackmate/spot-editor/trackmate-spot-editor-alpha-transparency.png new file mode 100644 index 000000000..9063a8526 Binary files /dev/null and b/media/plugins/trackmate/spot-editor/trackmate-spot-editor-alpha-transparency.png differ diff --git a/media/plugins/trackmate/spot-editor/trackmate-spot-editor-six-tools-annotation-bis.png b/media/plugins/trackmate/spot-editor/trackmate-spot-editor-six-tools-annotation-bis.png new file mode 100644 index 000000000..ffb78cdae Binary files /dev/null and b/media/plugins/trackmate/spot-editor/trackmate-spot-editor-six-tools-annotation-bis.png differ diff --git a/media/plugins/trackmate/spot-editor/trackmate-spot-editor-six-tools-annotation.png b/media/plugins/trackmate/spot-editor/trackmate-spot-editor-six-tools-annotation.png new file mode 100644 index 000000000..aeb8c62c0 Binary files /dev/null and b/media/plugins/trackmate/spot-editor/trackmate-spot-editor-six-tools-annotation.png differ diff --git a/media/plugins/trackmate/spot-editor/trackmate-spot-editor-six-tools.png b/media/plugins/trackmate/spot-editor/trackmate-spot-editor-six-tools.png new file mode 100644 index 000000000..1c4cd03a2 Binary files /dev/null and b/media/plugins/trackmate/spot-editor/trackmate-spot-editor-six-tools.png differ