LineageRegistration: add javadoc

maarzt · maarzt · commit 13121eb3dd83 · 2023-02-28T14:05:25.000+01:00
diff --git a/src/main/java/org/mastodon/mamut/tomancak/lineage_registration/LineageRegistrationControlService.java b/src/main/java/org/mastodon/mamut/tomancak/lineage_registration/LineageRegistrationControlService.java
@@ -18,6 +18,17 @@
 import org.scijava.plugin.Plugin;
 import org.scijava.service.AbstractService;
 
+/**
+ * This class is the controller for the {@link LineageRegistrationDialog}.
+ * It shows the dialog and performs the actions requested by the user.
+ * <p>
+ * There should be only one instance of this class in the Fiji application.
+ * This is ensured by making it an {@link ImageJService}. Being a service,
+ * allows the {@link LineageRegistrationPlugin} to access it, and to call
+ * {@link #registerMastodonInstance(WindowManager)}.
+ *
+ * @author Matthias Arzt
+ */
 @Plugin( type = ImageJService.class )
 public class LineageRegistrationControlService extends AbstractService implements ImageJService
 {
diff --git a/src/main/java/org/mastodon/mamut/tomancak/lineage_registration/LineageRegistrationDialog.java b/src/main/java/org/mastodon/mamut/tomancak/lineage_registration/LineageRegistrationDialog.java
@@ -22,6 +22,10 @@
 import org.mastodon.mamut.WindowManager;
 import org.mastodon.mamut.project.MamutProject;
 
+/**
+ * Dialog for the {@link LineageRegistrationPlugin}. It allows to select two
+ * {@link MamutProject}s and to perform various actions on them.
+ */
 public class LineageRegistrationDialog extends JDialog
 {
 	private static final String SORT_TRACKSCHEME_TOOLTIP = "<html><body>"
diff --git a/src/main/java/org/mastodon/mamut/tomancak/lineage_registration/LineageRegistrationPlugin.java b/src/main/java/org/mastodon/mamut/tomancak/lineage_registration/LineageRegistrationPlugin.java
@@ -21,9 +21,10 @@
 import org.scijava.ui.behaviour.util.RunnableAction;
 
 /**
- * Shows the {@link LineageRegistrationDialog} and
- * executes the {@link LineageRegistrationAlgorithm} when
- * ok is clicked.
+ * A plugin that registers the cell lineages of two stereotypically developing.
+ * <p>
+ * The plugin interacts with the {@link LineageRegistrationControlService} to
+ * register the {@link MamutPluginAppModel} and tho show the {@link LineageRegistrationDialog}.
  */
 @Plugin( type = MamutPlugin.class )
 public class LineageRegistrationPlugin implements MamutPlugin
diff --git a/src/main/java/org/mastodon/mamut/tomancak/lineage_registration/LineageRegistrationUtils.java b/src/main/java/org/mastodon/mamut/tomancak/lineage_registration/LineageRegistrationUtils.java
@@ -21,15 +21,32 @@
 import org.mastodon.model.tag.ObjTagMap;
 import org.mastodon.model.tag.TagSetStructure;
 
+/**
+ * Utility class that implements most of the functionality
+ * provided by the {@link LineageRegistrationPlugin}.
+ */
 public class LineageRegistrationUtils
 {
 
+	/**
+	 * Sorts the descendants in the second {@link ModelGraph} to match the order
+	 * of the descendants in the first {@link ModelGraph}.
+	 * The sorting is based on the result of the
+	 * {@link LineageRegistrationAlgorithm}.
+	 */
 	public static void sortSecondTrackSchemeToMatch( Model modelA, Model modelB )
 	{
 		RegisteredGraphs result = LineageRegistrationAlgorithm.run( modelA.getGraph(), modelB.getGraph() );
-		FlipDescendants.flipDescendants( modelB, getSpotsToFlipB( result ) );
+		RefList< Spot > spotsToFlipB = getSpotsToFlipB( result );
+		FlipDescendants.flipDescendants( modelB, spotsToFlipB );
 	}
 
+	/**
+	 * Copy a tag set from modelA to modelB.
+	 * The {@link LineageRegistrationAlgorithm} is used to find the matching
+	 * between the branches in modelA and modelB. The tags are copied from
+	 * the branches  in modelA to the corresponding branches in modelB.
+	 */
 	public static TagSetStructure.TagSet copyTagSetToSecond( Model modelA, Model modelB,
 			TagSetStructure.TagSet tagSetModelA, String newTagSetName )
 	{
@@ -116,6 +133,10 @@ private static Function< TagSetStructure.Tag, TagSetStructure.Tag > getTagMap( T
 		return map::get;
 	}
 
+	/**
+	 * Creates a new tag set in both models. It runs the {@link LineageRegistrationAlgorithm}
+	 * and tags unmatched and flipped cells / branches.
+	 */
 	public static void tagCells( Model modelA, Model modelB, boolean modifyA, boolean modifyB )
 	{
 		RegisteredGraphs result = LineageRegistrationAlgorithm.run( modelA.getGraph(), modelB.getGraph() );
@@ -146,6 +167,10 @@ private static RefList< Spot > getSpotsToFlipB( RegisteredGraphs result )
 		return getSpotsToFlipA( result.swapAB() );
 	}
 
+	/**
+	 * Returns the spots in graph A that need to be flipped in order for the
+	 * descendants of graph A to match the order of the descendants in graph B.
+	 */
 	public static RefList< Spot > getSpotsToFlipA( RegisteredGraphs r )
 	{
 		Spot refA = r.graphA.vertexRef();
@@ -172,6 +197,11 @@ public static RefList< Spot > getSpotsToFlipA( RegisteredGraphs r )
 		}
 	}
 
+	/**
+	 * Returns true if the descendants of dividingA are in the opposite order
+	 * to the descendants of dividingB. Which descendant corresponds to which
+	 * is determined by the mapping {@link RegisteredGraphs#mapAB}.
+	 */
 	private static boolean doesRequireFlip( RegisteredGraphs r, Spot dividingA, Spot dividingB )
 	{
 		Spot refA = r.graphA.vertexRef();
@@ -195,6 +225,10 @@ private static boolean doesRequireFlip( RegisteredGraphs r, Spot dividingA, Spot
 		}
 	}
 
+	/**
+	 * Returns a list of branch starts in graph A that are not mapped to any
+	 * branch in graph B.
+	 */
 	public static RefSet< Spot > getUnmatchSpotsA( RegisteredGraphs r )
 	{
 		RefSet< Spot > branchStarts = BranchGraphUtils.getAllBranchStarts( r.graphA );

Original file line number	Diff line number	Diff line change
`@@ -21,15 +21,32 @@`
`21`	`21`	`import org.mastodon.model.tag.ObjTagMap;`
`22`	`22`	`import org.mastodon.model.tag.TagSetStructure;`
`23`	`23`
	`24`	`+/**`
	`25`	`+ * Utility class that implements most of the functionality`
	`26`	`+ * provided by the {@link LineageRegistrationPlugin}.`
	`27`	`+ */`
`24`	`28`	`public class LineageRegistrationUtils`
`25`	`29`	`{`
`26`	`30`
	`31`	`+ /**`
	`32`	`+ * Sorts the descendants in the second {@link ModelGraph} to match the order`
	`33`	`+ * of the descendants in the first {@link ModelGraph}.`
	`34`	`+ * The sorting is based on the result of the`
	`35`	`+ * {@link LineageRegistrationAlgorithm}.`
	`36`	`+ */`
`27`	`37`	`public static void sortSecondTrackSchemeToMatch( Model modelA, Model modelB )`
`28`	`38`	`{`
`29`	`39`	`RegisteredGraphs result = LineageRegistrationAlgorithm.run( modelA.getGraph(), modelB.getGraph() );`
`30`		`- FlipDescendants.flipDescendants( modelB, getSpotsToFlipB( result ) );`
	`40`	`+ RefList< Spot > spotsToFlipB = getSpotsToFlipB( result );`
	`41`	`+ FlipDescendants.flipDescendants( modelB, spotsToFlipB );`
`31`	`42`	`}`
`32`	`43`
	`44`	`+ /**`
	`45`	`+ * Copy a tag set from modelA to modelB.`
	`46`	`+ * The {@link LineageRegistrationAlgorithm} is used to find the matching`
	`47`	`+ * between the branches in modelA and modelB. The tags are copied from`
	`48`	`+ * the branches in modelA to the corresponding branches in modelB.`
	`49`	`+ */`
`33`	`50`	`public static TagSetStructure.TagSet copyTagSetToSecond( Model modelA, Model modelB,`
`34`	`51`	`TagSetStructure.TagSet tagSetModelA, String newTagSetName )`
`35`	`52`	`{`
`@@ -116,6 +133,10 @@ private static Function< TagSetStructure.Tag, TagSetStructure.Tag > getTagMap( T`
`116`	`133`	`return map::get;`
`117`	`134`	`}`
`118`	`135`
	`136`	`+ /**`
	`137`	`+ * Creates a new tag set in both models. It runs the {@link LineageRegistrationAlgorithm}`
	`138`	`+ * and tags unmatched and flipped cells / branches.`
	`139`	`+ */`
`119`	`140`	`public static void tagCells( Model modelA, Model modelB, boolean modifyA, boolean modifyB )`
`120`	`141`	`{`
`121`	`142`	`RegisteredGraphs result = LineageRegistrationAlgorithm.run( modelA.getGraph(), modelB.getGraph() );`
`@@ -146,6 +167,10 @@ private static RefList< Spot > getSpotsToFlipB( RegisteredGraphs result )`
`146`	`167`	`return getSpotsToFlipA( result.swapAB() );`
`147`	`168`	`}`
`148`	`169`
	`170`	`+ /**`
	`171`	`+ * Returns the spots in graph A that need to be flipped in order for the`
	`172`	`+ * descendants of graph A to match the order of the descendants in graph B.`
	`173`	`+ */`
`149`	`174`	`public static RefList< Spot > getSpotsToFlipA( RegisteredGraphs r )`
`150`	`175`	`{`
`151`	`176`	`Spot refA = r.graphA.vertexRef();`
`@@ -172,6 +197,11 @@ public static RefList< Spot > getSpotsToFlipA( RegisteredGraphs r )`
`172`	`197`	`}`
`173`	`198`	`}`
`174`	`199`
	`200`	`+ /**`
	`201`	`+ * Returns true if the descendants of dividingA are in the opposite order`
	`202`	`+ * to the descendants of dividingB. Which descendant corresponds to which`
	`203`	`+ * is determined by the mapping {@link RegisteredGraphs#mapAB}.`
	`204`	`+ */`
`175`	`205`	`private static boolean doesRequireFlip( RegisteredGraphs r, Spot dividingA, Spot dividingB )`
`176`	`206`	`{`
`177`	`207`	`Spot refA = r.graphA.vertexRef();`
`@@ -195,6 +225,10 @@ private static boolean doesRequireFlip( RegisteredGraphs r, Spot dividingA, Spot`
`195`	`225`	`}`
`196`	`226`	`}`
`197`	`227`
	`228`	`+ /**`
	`229`	`+ * Returns a list of branch starts in graph A that are not mapped to any`
	`230`	`+ * branch in graph B.`
	`231`	`+ */`
`198`	`232`	`public static RefSet< Spot > getUnmatchSpotsA( RegisteredGraphs r )`
`199`	`233`	`{`
`200`	`234`	`RefSet< Spot > branchStarts = BranchGraphUtils.getAllBranchStarts( r.graphA );`