Package qupath.lib.scripting

Class QP

java.lang.Object
qupath.lib.scripting.QP
Direct Known Subclasses:
QPEx
public class QP extends Object
Collection of static methods that are useful for scripting.

Prior to running a script, the ImageData should be set so that the script can make use of it.

A different ImageData may be stored for different threads.

Note: This design may change in the future, to enable a non-static class to encapsulate the context for a running script. The limited ability to subclass a class containing static methods makes this design a bit problematic, while its package location means it cannot have access to GUI features (which it shouldn't have, because of the need to run headless... but sometimes the GUI is needed, e.g. to export images with markup).

Author:
Pete Bankhead

  • Field Details

    • BRIGHTFIELD_H_DAB

      public static final ImageData.ImageType BRIGHTFIELD_H_DAB
      Brightfield image type with hematoxylin and DAB staining

    • BRIGHTFIELD_H_E

      public static final ImageData.ImageType BRIGHTFIELD_H_E
      Brightfield image type with hematoxylin and eosin staining

    • BRIGHTFIELD_OTHER

      public static final ImageData.ImageType BRIGHTFIELD_OTHER
      Brightfield image type

    • FLUORESCENCE

      public static final ImageData.ImageType FLUORESCENCE
      Fluorescence image type

    • OTHER

      public static final ImageData.ImageType OTHER
      Any other image type (neither brightfield nor fluorescence)

    • PROJECT_BASE_DIR

      public static final String PROJECT_BASE_DIR
      Placeholder for the path to the current project. May be used as follows: 
         var path = buildFilePath(PROJECT_BASE_DIR, 'subdir', 'name.txt')
      See Also:

    • VERSION

      public static final Version VERSION
      The current QuPath version, parsed according to semantic versioning. May be null if the version is not known.

  • Constructor Details

    • QP

      public QP()

  • Method Details

    • describe

      public static String describe(Object o)
      List the fields and methods of a specified object.
      Parameters:
      o -
      Returns:

    • describe

      public static String describe(Class<?> cls)
      List the fields and methods of a specified class.
      Parameters:
      cls -
      Returns:

    • getCoreClasses

      public static Collection<Class<?>> getCoreClasses()
      Get a list of core classes that are likely to be useful for scripting. The purpose of this is to allow users to find classes they are likely to need, or to import these automatically at the beginning of scripts.
      Returns:

    • setDefaultProject

      public static void setDefaultProject(Project<BufferedImage> project)
      Set the default project, which will be returned by getProject() if it would otherwise return null (i.e. there has been no project set for the calling thread via setBatchProjectAndImage(Project, ImageData)).

      The intended use is for QuPath to set this to be the current project in the user interface, when running interactively.

      Parameters:
      project -

    • setDefaultImageData

      public static void setDefaultImageData(ImageData<BufferedImage> imageData)
      Set the default image data, which will be returned by getCurrentImageData() if it would otherwise return null (i.e. there has been no project set for the calling thread via setBatchProjectAndImage(Project, ImageData)).

      The intended use is for QuPath to set this to be the current image data in the user interface, when running interactively. This is not necessarily always the image that is 'current' when running scripts, e.g. when batch processing.

      Parameters:
      imageData -

    • setBatchProjectAndImage

      public static void setBatchProjectAndImage(Project<BufferedImage> project, ImageData<BufferedImage> imageData)
      Set the Project and ImageData to use for batch processing for the current thread.
      Parameters:
      project -
      imageData -

    • resetBatchProjectAndImage

      public static void resetBatchProjectAndImage()
      Reset the Project and ImageData used for batch processing for the current thread.

    • loadImageData

      @Deprecated public static ImageData<BufferedImage> loadImageData(String path, boolean setBatchData) throws IOException
      Deprecated.
      Load ImageData from a file.
      Parameters:
      path - path to the file containing ImageData.
      setBatchData - if true, the setBatchImageData(ImageData) will be called if the loading is successful.
      Returns:
      Throws:
      IOException
      See Also:
      • setBatchImageData(qupath.lib.images.ImageData<java.awt.image.BufferedImage>)

    • fireHierarchyUpdate

      public static void fireHierarchyUpdate()
      Trigger an update for the current hierarchy.

      This should be called after any (non-standard) modifications are made to the hierarchy to ensure that all listeners are notified (including for any GUI).

      It is common to call it at the end of any script that does any direct modification of objects (e.g. adding/removing measurements, setting classifications).

    • fireHierarchyUpdate

      public static void fireHierarchyUpdate(PathObjectHierarchy hierarchy)
      Trigger an update for the specified hierarchy.

      This should be called after any (non-standard) modifications are made to the hierarchy to ensure that all listeners are notified (including for any GUI).

      It is common to call it at the end of any script that does any direct modification of objects (e.g. adding/removing measurements, setting classifications).

      Parameters:
      hierarchy -

    • getColorRGB

      @Deprecated public static Integer getColorRGB(int... v)
      Deprecated.
      Use instead makeRGB(int, int, int) or makeARGB(int, int, int, int)
      Create a new packed-int representation of an RGB color.

      Parameters:
      v - A value between 0 and 255. If a single value is give, the result will be a shade of gray (RGB all with that value). Otherwise, 3 or 4 values may be given to generate either an RGB or RGBA color. Note: values are expected in order RGBA, but Java's packed ints are really ARGB.
      Returns:

    • makeRGB

      public static Integer makeRGB(int r, int g, int b)
      Make a packed int representation of an RGB color. Alpha defaults to 255. Red, green and blue values should be in the range 0-255; if they are not, they will be clipped.
      Parameters:
      r -
      g -
      b -
      Returns:

    • makeARGB

      public static Integer makeARGB(int a, int r, int g, int b)
      Make a packed int representation of an ARGB color. Alpha, red, green and blue values should be in the range 0-255; if they are not, they will be clipped.
      Parameters:
      a -
      r -
      g -
      b -
      Returns:

    • getCurrentServerPath

      public static String getCurrentServerPath()
      Get the path to the ImageServer of the current ImageData.
      Returns:
      See Also:

    • getCurrentImageData

      public static ImageData<BufferedImage> getCurrentImageData()
      Get the path to the current ImageData.

      This returns getBatchImageData() if it is not null; otherwise, it returns the default image data last set through setDefaultImageData(ImageData).

      Returns:
      See Also:
      • getBatchImageData()

    • getProject

      public static Project<BufferedImage> getProject()
      Get the current project.

      This returns getBatchProject() if it is not null; otherwise, it returns the default project last set through setDefaultProject(Project).

      Returns:
      See Also:
      • getBatchProject()

    • resolvePath

      public static String resolvePath(String path) throws IllegalArgumentException
      Resolve a path, replacing any placeholders. Currently, this means only PROJECT_BASE_DIR.
      Parameters:
      path -
      Returns:
      Throws:
      IllegalArgumentException - if PROJECT_BASE_DIR is used but no project is available

    • buildFilePath

      public static String buildFilePath(String first, String... more) throws IllegalArgumentException
      Build a file path from multiple components. A common use of this is 
      
   String path = buildFilePath(PROJECT_BASE_DIR, "export");
      although that can now be replaced by buildPathInProject(String...)
      Parameters:
      first - the first component of the file path
      more - additional path components to append
      Returns:
      Throws:
      IllegalArgumentException - if PROJECT_BASE_DIR is used but no project is available
      See Also:

    • buildPathInProject

      public static String buildPathInProject(String... more) throws IllegalArgumentException
      Build a file or directory path relative to the current project, but do not make any changes on the file system. This is equivalent to calling 
      
   String path = buildFilePath(PROJECT_BASE_DIR, more);

      If you want to additionally create the directory, see makePathInProject(String...)

      Parameters:
      more - additional path components to append
      Returns:
      Throws:
      IllegalArgumentException - if no project path is available
      Since:
      v0.4.0
      See Also:

    • makePathInProject

      public static String makePathInProject(String... more) throws IllegalArgumentException
      Build a file or directory path relative to the current project, and ensure that it exists. If it does not, an attempt will be made to create a directory with the specified name, and all necessary parent directories.

      This is equivalent to calling 

      
   String path = buildPathInProject(PROJECT_BASE_DIR, more);
   mkdirs(path);

      Note that if you need a file and not a directory, see makeFileInProject(String...).

      Parameters:
      more - additional path components to append
      Returns:
      Throws:
      IllegalArgumentException - if no project path is available
      Since:
      v0.4.0
      See Also:

    • makeFileInProject

      public static File makeFileInProject(String... more) throws IllegalArgumentException
      Build a file path relative to the current project, and create a File object. An attempt will be made to create any required directories needed to create the file.

      The purpose is to reduce the lines of code needed to build a usable file in a QuPath script. A Groovy script showing this method in action: 

         File file = makeFileInProject("export", "file.txt")
   file.text = "Some text here"

      Note that, if the file does not already exist, it will not be created by this method - only the directories leading to it. Additionally, if the file refers to an existing directory then the directory will be returned - and will not be writable as a file.

      Parameters:
      more - additional path components to append
      Returns:
      the file object, which may or may not refer to a file or directory that exists
      Throws:
      IllegalArgumentException - if no project path is available
      Since:
      v0.4.0
      See Also:

    • mkdirs

      public static boolean mkdirs(String path)
      Ensure directories exist for the specified path, calling file.mkdirs() if not.
      Parameters:
      path - the directory path
      Returns:
      true if a directory was created, false otherwise

    • fileExists

      public static boolean fileExists(String path)
      Query if a file exists.
      Parameters:
      path - full file path
      Returns:
      true if the file exists, false otherwise

    • isDirectory

      public static boolean isDirectory(String path)
      Query if a file path corresponds to a directory.
      Parameters:
      path - full file path
      Returns:
      true if the file exists and is a directory, false otherwise

    • getProjectEntry

      public static ProjectImageEntry<BufferedImage> getProjectEntry()
      Get the project entry for the currently-open image within the current project, or null if no project/image is open.
      Returns:

    • getProjectEntryMetadataValue

      public static String getProjectEntryMetadataValue(String key)
      Get the metadata value from the current project entry for the specified key, or null if no such metadata value exists (or no project entry is open).
      Parameters:
      key -
      Returns:

    • getCurrentHierarchy

      public static PathObjectHierarchy getCurrentHierarchy()
      Get the PathObjectHierarchy of the current ImageData.
      Returns:
      See Also:

    • getCurrentServer

      public static ImageServer<?> getCurrentServer()
      Get the ImageServer of the current ImageData.
      Returns:
      See Also:

    • getCurrentImageName

      public static String getCurrentImageName()
      Get the name of the current image.

      This first checks the name associated with getProjectEntry(), if available. If no name is found (e.g. because no project is in use, then the name is extracted from the metadata of getCurrentServer(). If this is also missing, then null is returned.

      Returns:
      Since:
      v0.4.0
      See Also:

    • getCurrentImageNameWithoutExtension

      public static String getCurrentImageNameWithoutExtension()
      Get the name of the current image, removing any file extension. Equivalent to 
      
 var name = GeneralTools.getNameWithoutExtension(getCurrentName());
      Returns:
      Since:
      v0.4.0
      See Also:

    • getSelectedObjects

      public static Collection<PathObject> getSelectedObjects()
      Get the selected objects within the current PathObjectHierarchy.

      Note: this implementation returns the selected objects directly. The returned collection may not be modifiable.

      Returns:
      See Also:

    • getSelectedObject

      public static PathObject getSelectedObject()
      Get the primary selected object within the current PathObjectHierarchy.
      Returns:
      See Also:

    • getSelectedROI

      public static ROI getSelectedROI()
      Get the ROI for the primary selected object within the current PathObjectHierarchy.

      This is really a convenience method where the selection indicates (for example) a region that should be extracted.

      Returns:
      See Also:

    • resetSelection

      public static void resetSelection()
      Clear the selected objects for the current PathObjectHierarchy.

    • setSelectedObject

      public static boolean setSelectedObject(PathObject pathObject)
      Set the selected object for the current PathObjectHierarchy.
      Parameters:
      pathObject - the object to select.
      Returns:
      See Also:

    • addObject

      public static void addObject(PathObject pathObject)
      Add the specified object to the current PathObjectHierarchy.

      This will trigger a hierarchy changed event.

      Parameters:
      pathObject -

    • addObjects

      public static void addObjects(PathObject[] pathObjects)
      Add the specified array of objects to the current PathObjectHierarchy.

      This will trigger a hierarchy changed event.

      Parameters:
      pathObjects -

    • addObjects

      public static void addObjects(Collection<PathObject> pathObjects)
      Add the specified collection of objects to the current PathObjectHierarchy.

      This will trigger a hierarchy changed event.

      Parameters:
      pathObjects -

    • removeObject

      public static void removeObject(PathObject pathObject, boolean keepChildren)
      Remove the specified object from the current PathObjectHierarchy, optionally keeping or removing descendant objects.
      Parameters:
      pathObject -
      keepChildren -

    • removeObjects

      public static void removeObjects(PathObject[] pathObjects, boolean keepChildren)
      Remove the specified array of objects from the current PathObjectHierarchy, optionally keeping or removing descendant objects.
      Parameters:
      pathObjects -
      keepChildren -

    • nObjects

      public static int nObjects()
      Get a count of the total number of objects in the current hierarchy.
      Returns:
      See Also:

    • removeObjects

      public static void removeObjects(Collection<? extends PathObject> pathObjects, boolean keepChildren)
      Remove the specified collection of objects from the current PathObjectHierarchy, optionally keeping or removing descendant objects.
      Parameters:
      pathObjects -
      keepChildren -

    • isTMADearrayed

      public static boolean isTMADearrayed()
      Returns true if TMA cores are available.
      Returns:

    • clearAllObjects

      public static void clearAllObjects()
      Remove all the objects in the current PathObjectHierarchy, and clear the selection.
      See Also:

    • clearAllObjects

      public static void clearAllObjects(Class<? extends PathObject> cls)
      Remove all the objects of a specified Java class.
      Parameters:
      cls - the class, e.g. PathAnnotationObject.class, PathDetectionObject.class, or null if all objects should be removed.
      See Also:

    • clearAnnotations

      public static void clearAnnotations()
      Remove all the annotation objects from the current PathObjectHierarchy.
      See Also:

    • clearDetections

      public static void clearDetections()
      Remove all the detection objects from the current PathObjectHierarchy.
      See Also:

    • clearTMAGrid

      public static void clearTMAGrid()
      Remove the TMA grid from the current PathObjectHierarchy.
      See Also:

    • addShapeMeasurements

      public static void addShapeMeasurements(String... features)
      Add the specified shape measurements to the current selected objects of the current image. If no features are specified, all will be added.
      Parameters:
      features -

    • addShapeMeasurements

      public static void addShapeMeasurements(ImageData<?> imageData, Collection<? extends PathObject> pathObjects, String feature, String... additionalFeatures)
      Add shape measurements to the specified objects.

      Note addShapeMeasurements(ImageData, Collection, ShapeFeatures...) can be used without specifying any features. This method requires at least one feature so as to have a distinct method signature.

      Parameters:
      imageData - the image to which the objects belong. This is used to determine pixel calibration and to fire an update event. May be null.
      pathObjects - the objects that should be measured
      feature - first feature to add
      additionalFeatures - optional array of Strings specifying the features to add

    • addShapeMeasurements

      public static void addShapeMeasurements(ImageData<?> imageData, Collection<? extends PathObject> pathObjects, ObjectMeasurements.ShapeFeatures... features)
      Add shape measurements to the specified objects.
      Parameters:
      imageData - the image to which the objects belong. This is used to determine pixel calibration and to fire an update event. May be null.
      pathObjects - the objects that should be measured
      features - the specific features to add. If none are specified, all available features will be added.

    • setChannelNames

      public static void setChannelNames(String... names)
      Set the channel names for the current ImageData.
      Parameters:
      names -
      See Also:

    • setChannelNames

      public static void setChannelNames(ImageData<?> imageData, String... names)
      Set the channel names for the specified ImageData. It is not essential to pass names for all channels: by passing n values, the first n channel names will be set. Any name that is null will be left unchanged.
      Parameters:
      imageData -
      names -

    • setChannelColors

      public static void setChannelColors(Integer... colors)
      Set the channel colors for the current ImageData.
      Parameters:
      colors -
      See Also:

    • setChannelColors

      public static void setChannelColors(ImageData<?> imageData, Integer... colors)
      Set the channel colors for the specified ImageData. It is not essential to pass names for all channels: by passing n values, the first n channel names will be set. Any name that is null will be left unchanged.
      Parameters:
      imageData -
      colors -
      See Also:

    • setChannels

      public static void setChannels(ImageChannel... channels)
      Set the channels for the current ImageData.
      Parameters:
      channels -
      See Also:

    • setChannels

      public static void setChannels(ImageData<?> imageData, ImageChannel... channels)
      Set the channels for the specified ImageData. Note that number of channels provided must match the number of channels of the current image.

      Also, currently it is not possible to set channels for RGB images - attempting to do so will throw an IllegalArgumentException.

      Parameters:
      imageData -
      channels -
      See Also:

    • runPlugin

      public static boolean runPlugin(String className, String args) throws InterruptedException
      Run the specified plugin on the current ImageData.
      Parameters:
      className - the full Java class name for the plugin
      args - any arguments required by the plugin (usually a JSON-encoded map)
      Returns:
      Throws:
      InterruptedException
      See Also:

    • runPlugin

      public static boolean runPlugin(String className, ImageData<?> imageData, String args) throws InterruptedException
      Run the specified plugin on the specified ImageData.
      Parameters:
      className - the full Java class name for the plugin
      imageData - the ImageData to which the plugin should be applied
      args - any arguments required by the plugin (usually a JSON-encoded map)
      Returns:
      Throws:
      InterruptedException

    • runPlugin

      public static boolean runPlugin(String className, Map<String,?> args) throws InterruptedException
      Run the specified plugin on the current ImageData, using a map for arguments.
      Parameters:
      className - the full Java class name for the plugin
      args - the arguments
      Returns:
      Throws:
      InterruptedException
      Since:
      v0.4.0
      See Also:

    • runPlugin

      public static boolean runPlugin(String className, ImageData<?> imageData, Map<String,?> args) throws InterruptedException
      Run the specified plugin on the specified ImageData, using a map for arguments.
      Parameters:
      className - the full Java class name for the plugin
      imageData - the ImageData to which the plugin should be applied
      args - the arguments
      Returns:
      Throws:
      InterruptedException
      Since:
      v0.4.0

    • runPlugin

      public static boolean runPlugin(Map<String,?> args, String className) throws InterruptedException
      Run the specified plugin on the current ImageData, with Groovy keyword argument support.

      This reason is that this Groovy supports keyword arguments, but only if a Map is the first argument to a method. This therefore makes it possible to change only non-default arguments with a call like this: 

      
 runPlugin('qupath.imagej.detect.cells.WatershedCellDetection', cellExpansionMicrons: 3, detectionImage: "DAPI", threshold: 1.0)
      It is not even essential to provide the required className in the first position.
      Parameters:
      args - the arguments
      className - the full Java class name for the plugin
      Returns:
      Throws:
      InterruptedException
      Since:
      v0.4.0

    • runPlugin

      public static boolean runPlugin(Map<String,?> args, String className, ImageData<?> imageData) throws InterruptedException
      Run the specified plugin on the specified ImageData, with Groovy keyword argument support.

      This reason is that this Groovy supports keyword arguments, but only if a Map is the first argument to a method. This therefore makes it possible to change only non-default arguments with a call like this: 

      
 runPlugin('qupath.imagej.detect.cells.WatershedCellDetection', imageData, cellExpansionMicrons: 3, detectionImage: "DAPI", threshold: 1.0)
      It is not even essential to provide the required className in the first position.
      Parameters:
      args - the arguments
      className - the full Java class name for the plugin
      imageData -
      Returns:
      Throws:
      InterruptedException
      Since:
      v0.4.0

    • getTMACoreList

      public static List<TMACoreObject> getTMACoreList()
      Get the list of TMA core objects for the current hierarchy.
      Returns:
      the list of TMACoreObjects, or an empty list if there is no TMA grid present.
      See Also:

    • getAnnotationObjects

      public static Collection<PathObject> getAnnotationObjects()
      Get a list of the current annotation objects.
      Returns:
      See Also:

    • getDetectionObjects

      public static Collection<PathObject> getDetectionObjects()
      Get a list of the current detection objects.
      Returns:
      See Also:

    • getTileObjects

      public static Collection<PathObject> getTileObjects()
      Get a list of the current tile objects.
      Returns:
      Since:
      v0.4.0
      See Also:

    • getCellObjects

      public static Collection<PathObject> getCellObjects()
      Get a list of the current cell objects.
      Returns:
      See Also:

    • getAllObjects

      public static Collection<PathObject> getAllObjects(boolean includeRootObject)
      Get all objects in the current hierarchy.
      Parameters:
      includeRootObject -
      Returns:
      See Also:

    • getAllObjects

      public static Collection<PathObject> getAllObjects()
      Get all objects in the current hierarchy, including the root object.
      Returns:
      See Also:

    • setImageType

      public static boolean setImageType(String typeName)
      Set the image type for the current image data, using a String to represent the enum ImageData.ImageType
      Parameters:
      typeName -
      Returns:

    • setImageType

      public static boolean setImageType(ImageData.ImageType type)
      Set the image type for the current image data
      Parameters:
      type -
      Returns:

    • setColorDeconvolutionStains

      public static boolean setColorDeconvolutionStains(String arg)
      Set the color deconvolution stains for hte current image data using a (JSON) String representation
      Parameters:
      arg -
      Returns:

    • createSelectAllObject

      @Deprecated public static void createSelectAllObject(boolean setSelected)
      Deprecated.
      v0.4.0 use createFullImageAnnotation(boolean) instead
      Create an annotation for the entire width and height of the current image data, on the default plane (z-slice, time point).
      Parameters:
      setSelected - if true, select the object that was created after it is added to the hierarchy

    • createSelectAllObject

      @Deprecated public static void createSelectAllObject(boolean setSelected, int z, int t)
      Deprecated.
      v0.4.0 use createFullImageAnnotation(boolean, int, int) instead
      Create an annotation for the entire width and height of the current image data, on the default plane (z-slice, time point).
      Parameters:
      setSelected - if true, select the object that was created after it is added to the hierarchy
      z - z-slice index for the annotation
      t - timepoint index for the annotation

    • createAllFullImageAnnotations

      public static List<PathObject> createAllFullImageAnnotations(boolean setSelected)
      Create annotation around the full image for the current image, on all z-slices and timepoints.
      Parameters:
      setSelected - if true, set the annotations to be selected when they are created
      Returns:
      the annotations that were created, or an empty list if no image data was available
      Since:
      v0.4.0
      See Also:

    • createAllFullImageAnnotations

      public static List<PathObject> createAllFullImageAnnotations(ImageData<?> imageData, boolean setSelected)
      Create annotation around the full image for the specified image, on all z-slices and timepoints.
      Parameters:
      imageData - the image data
      setSelected - if true, set the annotations to be selected when they are created
      Returns:
      the annotations that were created, or an empty list if no image data was available
      Since:
      v0.4.0

    • createFullImageAnnotation

      public static PathObject createFullImageAnnotation(boolean setSelected)
      Create an annotation around the full image for the current image, on the default (first) z-slice and timepoint.
      Parameters:
      setSelected - if true, set the annotation to be selected when it is created
      Returns:
      the annotation that was created, or null if no image data was available
      Since:
      v0.4.0
      See Also:

    • createFullImageAnnotation

      public static PathObject createFullImageAnnotation(boolean setSelected, int z, int t)
      Create an annotation around the full image for the current image, on the specified z-slice and timepoint.
      Parameters:
      setSelected - if true, set the annotation to be selected when it is created
      z - z-slice (0-based index)
      t - timepoint (0-based index)
      Returns:
      the annotation that was created, or null if no image data was available
      Since:
      v0.4.0
      See Also:

    • createFullImageAnnotation

      public static PathObject createFullImageAnnotation(ImageData<?> imageData, boolean setSelected)
      Create an annotation around the full image for the specified image, on the default (first) z-slice and timepoint.
      Parameters:
      imageData - the image data for which the annotation should be added
      setSelected - if true, set the annotation to be selected when it is created
      Returns:
      the annotation that was created, or null if no image data was available
      Since:
      v0.4.0

    • createFullImageAnnotation

      public static PathObject createFullImageAnnotation(ImageData<?> imageData, boolean setSelected, int z, int t)
      Create an annotation around the full image for the specified image, on the specified z-slice and timepoint.
      Parameters:
      imageData - the image data for which the annotation should be added
      setSelected - if true, set the annotation to be selected when it is created
      z - z-slice (0-based index)
      t - timepoint (0-based index)
      Returns:
      the annotation that was created, or null if no image data was available
      Since:
      v0.4.0

    • buildServer

      @Deprecated public static <T> ImageServer<T> buildServer(String path, Class<T> cls, String... args) throws IOException
      Deprecated.
      In the usual case where BufferedImage is the class, use buildServer(String, String...) instead because it handles default args.
      Build an ImageServer with a specified class.
      Parameters:
      path - image path (usually a file path or URI)
      cls - generic type for the server (usually BufferedImage)
      args - optional arguments
      Returns:
      an ImageServer, if one could be build from the supplied arguments
      Throws:
      IOException - if unable to build the server
      See Also:

    • buildServer

      public static ImageServer<BufferedImage> buildServer(String path, String... args) throws IOException
      Build an ImageServer with the class BufferedImage.
      Parameters:
      path - image path (usually a file path or URI)
      args - optional arguments
      Returns:
      an ImageServer, if one could be build from the supplied arguments
      Throws:
      IOException - if unable to build the server
      See Also:

    • buildServer

      public static ImageServer<BufferedImage> buildServer(URI uri, String... args) throws IOException
      Build an ImageServer with the class BufferedImage.
      Parameters:
      uri - image URI
      args - optional arguments
      Returns:
      an ImageServer, if one could be build from the supplied arguments
      Throws:
      IOException - if unable to build the server
      Since:
      v0.3
      See Also:

    • transformSelectedObjects

      public static void transformSelectedObjects(AffineTransform transform)
      Apply an affine transform to all objects in the current hierarchy, retaining parent-child relationships between objects.
      Parameters:
      transform -
      Since:
      v0.4.0

    • transformSelectedObjects

      public static void transformSelectedObjects(PathObjectHierarchy hierarchy, AffineTransform transform)
      Apply an affine transform to all objects in the specified hierarchy, retaining parent-child relationships between objects.
      Parameters:
      hierarchy -
      transform -
      Since:
      v0.4.0

    • scaleAllObjects

      public static void scaleAllObjects(double scaleFactor)
      Resize the ROIs of all objects in the current object hierarchy.
      Parameters:
      scaleFactor - scale factor
      Since:
      v0.4.0
      See Also:

    • scaleAllObjects

      public static void scaleAllObjects(PathObjectHierarchy hierarchy, double scaleFactor)
      Resize the ROIs of all objects in the specified object hierarchy.
      Parameters:
      hierarchy - the object hierarchy
      scaleFactor - scale factor
      Since:
      v0.4.0
      See Also:

    • translateAllObjects

      public static void translateAllObjects(double dx, double dy)
      Translate (move) the ROIs of all objects in the current object hierarchy.
      Parameters:
      dx - amount to translate horizontally (in pixels)
      dy - amount to translate vertically (in pixels)
      Since:
      v0.4.0
      See Also:

    • translateAllObjects

      public static void translateAllObjects(PathObjectHierarchy hierarchy, double dx, double dy)
      Translate (move) the ROIs of all objects in the specified object hierarchy.
      Parameters:
      hierarchy - the object hierarchy
      dx - amount to translate horizontally (in pixels)
      dy - amount to translate vertically (in pixels)
      Since:
      v0.4.0
      See Also:

    • transformAllObjects

      public static void transformAllObjects(AffineTransform transform)
      Apply an affine transform to all selected objects in the current hierarchy. The selected objects will be replaced by new ones, but parent-child relationships will be lost; if these are needed, consider calling resolveHierarchy() afterwards.
      Parameters:
      transform -
      Since:
      v0.4.0

    • transformAllObjects

      public static void transformAllObjects(PathObjectHierarchy hierarchy, AffineTransform transform)
      Apply an affine transform to all selected objects in the specified hierarchy. The selected objects will be replaced by new ones, but parent-child relationships will be lost; if these are needed, consider calling resolveHierarchy(PathObjectHierarchy) afterwards.
      Parameters:
      hierarchy -
      transform -
      Since:
      v0.4.0

    • resetTMAMetadata

      public static void resetTMAMetadata(boolean includeMeasurements)
      Remove all TMA metadata from the current TMA grid.
      Parameters:
      includeMeasurements - remove measurements in addition to textual metadata

    • resetTMAMetadata

      public static void resetTMAMetadata(PathObjectHierarchy hierarchy, boolean includeMeasurements)
      Remove all TMA metadata from the TMA grid of the specified hierarchy.
      Parameters:
      hierarchy -
      includeMeasurements - remove measurements in addition to textual metadata

    • relabelTMAGrid

      public static boolean relabelTMAGrid(PathObjectHierarchy hierarchy, String labelsHorizontal, String labelsVertical, boolean rowFirst)
      Relabel a TMA grid. This will only be effective if enough labels are supplied for the full grid - otherwise no changes will be made.

      For a TMA core at column c and row r, the label format will be 'Hc-Vr' or 'Hc-Vr', where H is the horizontal label and V the vertical label, depending upon the status of the 'rowFirst' flag.

      An examples of label would be 'A-1', 'A-2', 'B-1', 'B-2' etc.

      Parameters:
      hierarchy - The hierarchy containing the TMA grid to be relabelled.
      labelsHorizontal - A String containing labels for each TMA column, separated by spaces, or a numeric or alphabetic range (e.g. 1-10, or A-G)
      labelsVertical - A String containing labels for each TMA row, separated by spaces, or a numeric or alphabetic range (e.g. 1-10, or A-G)
      rowFirst - true if the horizontal label should be added before the vertical label, false otherwise
      Returns:
      true if there were sufficient horizontal and vertical labels to label the entire grid, false otherwise.

    • relabelTMAGrid

      public static boolean relabelTMAGrid(String labelsHorizontal, String labelsVertical, boolean rowFirst)
      Relabel the current TMA grid. See relabelTMAGrid(PathObjectHierarchy, String, String, boolean)
      Parameters:
      labelsHorizontal -
      labelsVertical -
      rowFirst -
      Returns:

    • createTMAGrid

      public static void createTMAGrid(ImageData<?> imageData, String hLabels, String vLabels, boolean rowFirst, double diameterCalibrated)
      Create a new regular TMAGrid and set it as active on the hierarchy for an image.

      For the label string format, see see PathObjectTools.parseTMALabelString(String).

      Parameters:
      imageData - the image to which the TMA grid should be added. This is used to determine dimensions and pixel calibration. If there is a ROI selected, it will be used to define the bounding box for the grid.
      hLabels - a String representing horizontal labels
      vLabels - a String representing vertical labels
      rowFirst - true if the horizontal label should be added before the vertical label, false otherwise
      diameterCalibrated - the diameter of each core, in calibrated units
      See Also:

    • createTMAGrid

      public static void createTMAGrid(String hLabels, String vLabels, boolean rowFirst, double diameterCalibrated)
      Create a new regular TMAGrid and set it as active on the hierarchy for the current image.

      For the label string format, see see PathObjectTools.parseTMALabelString(String).

      Parameters:
      hLabels - a String representing horizontal labels
      vLabels - a String representing vertical labels
      rowFirst - true if the horizontal label should be added before the vertical label, false otherwise
      diameterCalibrated - the diameter of each core, in calibrated units
      See Also:

    • resetClassifications

      public static void resetClassifications(Class<? extends PathObject> cls)
      Reset the PathClass for all objects of the specified type in the current hierarchy.
      Parameters:
      cls -

    • refreshIDs

      public static void refreshIDs()
      Refresh all object IDs for the current hierarchy.
      Since:
      v0.4.0

    • refreshDuplicateIDs

      public static boolean refreshDuplicateIDs()
      Refresh all object IDs for the current hierarchy to ensure there are no duplicates, retaining the original IDs where possible.
      Returns:
      true if object IDs were changed, false otherwise
      Since:
      v0.4.0

    • refreshIDs

      public static void refreshIDs(PathObjectHierarchy hierarchy)
      Refresh all object IDs for the current hierarchy.
      Parameters:
      hierarchy - the object hierarchy
      Since:
      v0.4.0

    • refreshDuplicateIDs

      public static boolean refreshDuplicateIDs(PathObjectHierarchy hierarchy)
      Refresh all object IDs for the current hierarchy to ensure there are no duplicates, retaining the original IDs where possible.
      Parameters:
      hierarchy - the object hierarchy
      Returns:
      true if object IDs were changed, false otherwise
      Since:
      v0.4.0

    • resetClassifications

      public static void resetClassifications(PathObjectHierarchy hierarchy, Class<? extends PathObject> cls)
      Reset the PathClass for all objects of the specified type in the specified hierarchy.
      Parameters:
      hierarchy -
      cls -

    • resetDetectionClassifications

      public static void resetDetectionClassifications()
      Reset the PathClass for all detection objects in the current hierarchy.

    • hasMeasurement

      public static boolean hasMeasurement(PathObject pathObject, String measurementName)
      Test whether a PathObject has a specified measurement in its measurement list.
      Parameters:
      pathObject -
      measurementName -
      Returns:

    • measurement

      public static double measurement(PathObject pathObject, String measurementName)
      Extract the specified measurement from a PathObject.
      Parameters:
      pathObject -
      measurementName -
      Returns:

    • clearSelectedObjects

      public static void clearSelectedObjects()
      Clear selected objects, but keep child (descendant) objects.

    • clearSelectedObjects

      public static void clearSelectedObjects(boolean keepChildren)
      Delete the selected objects from the current hierarchy, optionally keeping their child (descendant) objects.
      Parameters:
      keepChildren -

    • getObjects

      public static List<PathObject> getObjects(Predicate<PathObject> predicate)
      Get a list of all objects in the current hierarchy according to a specified predicate.
      Parameters:
      predicate -
      Returns:

    • selectAllObjects

      public static void selectAllObjects(PathObjectHierarchy hierarchy, boolean includeRootObject)
      Set selected objects to contain all objects.
      Parameters:
      hierarchy -
      includeRootObject -

    • selectAllObjects

      public static void selectAllObjects(PathObjectHierarchy hierarchy)
      Select all objects in the specified hierarchy, excluding the root object.
      Parameters:
      hierarchy -
      Since:
      v0.4.0

    • selectAllObjects

      public static void selectAllObjects()
      Select all objects in the current hierarchy, excluding the root object.
      Since:
      v0.4.0

    • selectObjectsByPlane

      public static void selectObjectsByPlane(int z, int t)
      Selected objects in the current hierarchy occurring on the specified z-slice and timepoint.
      Parameters:
      z - z-slice (0-based index)
      t - timepoint (0-based index)
      Since:
      v0.4.0
      See Also:

    • selectObjectsByPlane

      public static void selectObjectsByPlane(ImagePlane plane)
      Selected objects in the current hierarchy occurring on the specified plane (z-slice and timepoint).
      Parameters:
      plane -
      Since:
      v0.4.0
      See Also:

    • selectObjectsByPlane

      public static void selectObjectsByPlane(PathObjectHierarchy hierarchy, ImagePlane plane)
      Selected objects in the specified hierarchy occurring on the specified plane (z-slice and timepoint).
      Parameters:
      hierarchy -
      plane -
      Since:
      v0.4.0

    • selectObjects

      public static void selectObjects(Predicate<PathObject> predicate)
      Set selected objects to contain (only) all objects in the current hierarchy according to a specified predicate.
      Parameters:
      predicate -

    • selectObjects

      public static void selectObjects(Collection<? extends PathObject> pathObjects)
      Set all objects in a collection to be selected, without any being chosen as the main object.
      Parameters:
      pathObjects -

    • selectObjects

      public static void selectObjects(Collection<? extends PathObject> pathObjects, PathObject mainSelection)
      Set all objects in a collection to be selected, including a specified main selected object.
      Parameters:
      pathObjects -
      mainSelection -

    • selectObjects

      public static void selectObjects(PathObjectHierarchy hierarchy, PathObject... pathObjects)
      Set one or more objects to be selected within the specified hierarchy.
      Parameters:
      hierarchy -
      pathObjects -

    • selectObjects

      public static void selectObjects(PathObject... pathObjects)
      Set one or more objects to be selected within the current hierarchy.
      Parameters:
      pathObjects -

    • getObjects

      public static List<PathObject> getObjects(PathObjectHierarchy hierarchy, Predicate<PathObject> predicate)
      Get a list of all objects in the specified hierarchy according to a specified predicate.
      Parameters:
      hierarchy -
      predicate -
      Returns:

    • selectObjects

      public static void selectObjects(PathObjectHierarchy hierarchy, Predicate<PathObject> predicate)
      Set selected objects to contain (only) all objects in the specified hierarchy according to a specified predicate.
      Parameters:
      hierarchy -
      predicate -

    • selectObjectsByClass

      public static void selectObjectsByClass(Class<? extends PathObject> cls)
      Set objects that are a subclass of a specified class. Not to be confused with selectObjectsByPathClass(PathClass...) and selectObjectsByClassification(String...).
      Parameters:
      cls -

    • selectObjectsByClass

      public static void selectObjectsByClass(PathObjectHierarchy hierarchy, Class<? extends PathObject> cls)
      Set objects that are a subclass of a specified class. Not to be confused with selectObjectsByPathClass(PathObjectHierarchy, PathClass...) and selectObjectsByClassification(PathObjectHierarchy, String...).
      Parameters:
      hierarchy -
      cls -

    • selectAnnotations

      public static void selectAnnotations(PathObjectHierarchy hierarchy)
      Select all annotation objects in the specified hierarchy.
      Parameters:
      hierarchy -

    • selectTMACores

      public static void selectTMACores(PathObjectHierarchy hierarchy)
      Select all TMA core objects in the specified hierarchy, excluding missing cores.
      Parameters:
      hierarchy -

    • selectTMACores

      public static void selectTMACores(PathObjectHierarchy hierarchy, boolean includeMissing)
      Select all TMA core objects in the specified hierarchy, optionally including missing cores.
      Parameters:
      hierarchy -
      includeMissing -

    • selectDetections

      public static void selectDetections(PathObjectHierarchy hierarchy)
      Select all detection objects in the specified hierarchy.
      Parameters:
      hierarchy -

    • selectCells

      public static void selectCells(PathObjectHierarchy hierarchy)
      Select all cell objects in the specified hierarchy.
      Parameters:
      hierarchy -

    • selectAnnotations

      public static void selectAnnotations()
      Select all annotation objects in the current hierarchy.

    • selectTMACores

      public static void selectTMACores()
      Select all TMA core objects in the current hierarchy, excluding missing cores.

    • selectTMACores

      public static void selectTMACores(boolean includeMissing)
      Select all TMA core objects in the current hierarchy, optionally including missing cores.
      Parameters:
      includeMissing -

    • selectDetections

      public static void selectDetections()
      Select all detection objects in the current hierarchy.

    • selectCells

      public static void selectCells()
      Select all cell objects in the current hierarchy.

    • selectTiles

      public static void selectTiles(PathObjectHierarchy hierarchy)
      Select all tile objects in the specified hierarchy.
      Parameters:
      hierarchy -

    • selectTiles

      public static void selectTiles()
      Select all tile objects in the current hierarchy.

    • selectObjectsByClassification

      public static void selectObjectsByClassification(String... pathClassNames)
      Select objects for the current hierarchy that have one of the specified classifications.
      Parameters:
      pathClassNames - one or more classification names, which may be converted to a PathClass with getPathClass(String)

    • selectObjectsByPathClass

      public static void selectObjectsByPathClass(PathClass... pathClasses)
      Select objects for the current hierarchy that have one of the specified PathClass classifications assigned.
      Parameters:
      pathClasses - one or more classifications
      See Also:

    • selectObjectsByClassification

      public static void selectObjectsByClassification(PathObjectHierarchy hierarchy, String... pathClassNames)
      Select objects for the specified hierarchy that have one of the specified classifications.
      Parameters:
      hierarchy - the hierarchy containing objects that may be selected
      pathClassNames - one or more classification names, which may be converted to a PathClass with getPathClass(String)
      See Also:

    • selectObjectsByPathClass

      public static void selectObjectsByPathClass(PathObjectHierarchy hierarchy, PathClass... pathClasses)
      Select objects for the specified hierarchy that have one of the specified PathClass classifications assigned.
      Parameters:
      hierarchy - the hierarchy containing objects that may be selected
      pathClasses - one or more classifications

    • selectObjectsByMeasurement

      @Deprecated public static void selectObjectsByMeasurement(ImageData<?> imageData, String command)
      Deprecated.
      Select objects based on a specified measurement.
      Parameters:
      imageData -
      command -

    • classifySelected

      public static void classifySelected(String pathClassName)
      Set the classification of the selected objects in the current hierarchy.
      Parameters:
      pathClassName -

    • classifySelected

      public static void classifySelected(PathObjectHierarchy hierarchy, String pathClassName)
      Set the classification of the selected objects.
      Parameters:
      hierarchy -
      pathClassName -

    • exportAllObjectsToGeoJson

      public static void exportAllObjectsToGeoJson(String path, String option, String... additionalOptions) throws IOException
      Export all objects (excluding root object) to an output file as GeoJSON.
      Parameters:
      path -
      option -
      additionalOptions -
      Throws:
      IOException

    • exportAllObjectsToGeoJson

      public static void exportAllObjectsToGeoJson(String path, PathIO.GeoJsonExportOptions... options) throws IOException
      Export all objects (excluding root object) to an output file as GeoJSON.
      Parameters:
      path -
      options -
      Throws:
      IOException

    • exportSelectedObjectsToGeoJson

      public static void exportSelectedObjectsToGeoJson(String path, String option, String... additionalOptions) throws IOException
      Export the selected objects to an output file as GeoJSON.
      Parameters:
      path -
      option -
      additionalOptions -
      Throws:
      IOException

    • exportSelectedObjectsToGeoJson

      public static void exportSelectedObjectsToGeoJson(String path, PathIO.GeoJsonExportOptions... options) throws IOException
      Export the selected objects to an output file as GeoJSON.
      Parameters:
      path -
      options -
      Throws:
      IOException

    • exportObjectsToGeoJson

      public static void exportObjectsToGeoJson(Collection<? extends PathObject> pathObjects, String path, String option, String... additionalOptions) throws IOException
      Export specified objects to an output file as GeoJSON.
      Parameters:
      pathObjects -
      path -
      option -
      additionalOptions -
      Throws:
      IOException

    • exportObjectsToGeoJson

      public static void exportObjectsToGeoJson(Collection<? extends PathObject> pathObjects, String path, PathIO.GeoJsonExportOptions... options) throws IOException
      Export specified objects to an output file as GeoJSON.
      Parameters:
      pathObjects -
      path -
      options -
      Throws:
      IOException

    • importObjectsFromFile

      public static boolean importObjectsFromFile(String path) throws FileNotFoundException, IllegalArgumentException, IOException, ClassNotFoundException
      Import all PathObjects from the given file.

      IllegalArgumentException is thrown if the file is not compatible.
      FileNotFoundException is thrown if the file is not found.
      IOException is thrown if an error occurs while reading the file.
      ClassNotFoundException should never occur naturally (except through a change in the code).

      Parameters:
      path -
      Returns:
      success
      Throws:
      FileNotFoundException
      IllegalArgumentException
      ClassNotFoundException
      IOException

    • deselectAll

      public static void deselectAll()
      Clear the selection for the current hierarchy, so that no objects of any kind are selected.

    • deselectAll

      public static void deselectAll(PathObjectHierarchy hierarchy)
      Clear the selection, so that no objects of any kind are selected.
      Parameters:
      hierarchy -

    • getPathClass

      public static PathClass getPathClass(String name)
      Get a PathClass with the specified name.
      Parameters:
      name -
      Returns:

    • getPathClass

      public static PathClass getPathClass(String name, Integer rgb)
      Get a PathClass with the specified name and color. Note that only one instance of any PathClass can exist at any time, therefore any existing PathClass with the same description will always be returned instead of creating a new one. In this case, the color attribute of the existing PathClass will not be changed. Therefore the color only has an effect when a new PathClass is created.
      Parameters:
      name -
      rgb -
      Returns:
      See Also:

    • getDerivedPathClass

      public static PathClass getDerivedPathClass(PathClass baseClass, String name)
      Get a PathClass with the specified name, derived from another PathClass. An example would be a 'positive' class derived from a 'Tumor' class, e.g. getDerivedPathClass(getPathClass("Tumor"), "Positive")
      Parameters:
      baseClass -
      name -
      Returns:

    • getDerivedPathClass

      public static PathClass getDerivedPathClass(PathClass baseClass, String name, Integer rgb)
      Get a PathClass with the specified name, derived from another PathClass. An example would be a 'positive' class derived from a 'Tumor' class, e.g. getDerivedPathClass(getPathClass("Tumor"), "Positive", getColorRGB(255, 0, 0)) Note that only one instance of any PathClass can exist at any time, therefore any existing PathClass with the same description will always be returned instead of creating a new one. In this case, the color attribute of the existing PathClass will not be changed. Therefore the color only has an effect when a new PathClass is created.
      Parameters:
      baseClass -
      name -
      rgb -
      Returns:

    • removeMeasurements

      public static void removeMeasurements(Class<? extends PathObject> cls, String... measurementNames)
      Remove measurements from objects of a specific class for the current image data.
      Parameters:
      cls -
      measurementNames -

    • removeMeasurements

      public static void removeMeasurements(PathObjectHierarchy hierarchy, Class<? extends PathObject> cls, String... measurementNames)
      Remove measurements from objects of a specific class for the specified hierarchy.
      Parameters:
      hierarchy -
      cls -
      measurementNames -

    • clearMeasurements

      public static void clearMeasurements(PathObjectHierarchy hierarchy, PathObject... pathObjects)
      Clear the measurement lists for specified objects within a hierarchy.
      Parameters:
      hierarchy - used to fire a hierarchy update, if specified (may be null if no update should be fired)
      pathObjects - collection of objects that should have their measurement lists cleared

    • clearMeasurements

      public static void clearMeasurements(PathObjectHierarchy hierarchy, Collection<PathObject> pathObjects)
      Clear the measurement lists for specified objects within a hierarchy.
      Parameters:
      hierarchy - used to fire a hierarchy update, if specified (may be null if no update should be fired)
      pathObjects - collection of objects that should have their measurement lists cleared

    • clearAnnotationMeasurements

      public static void clearAnnotationMeasurements(PathObjectHierarchy hierarchy)
      Clear the measurement lists for all annotations in a hierarchy.
      Parameters:
      hierarchy -

    • clearAnnotationMeasurements

      public static void clearAnnotationMeasurements()
      Clear the measurement lists for all annotations in the current hierarchy.

    • clearDetectionMeasurements

      public static void clearDetectionMeasurements(PathObjectHierarchy hierarchy)
      Clear the measurement lists for all detections in a hierarchy (including sub-classes of detections).
      Parameters:
      hierarchy -

    • clearDetectionMeasurements

      public static void clearDetectionMeasurements()
      Clear the measurement lists for all detections in the current hierarchy.

    • clearTMACoreMeasurements

      public static void clearTMACoreMeasurements(PathObjectHierarchy hierarchy)
      Clear the measurement lists for all TMA core objects in a hierarchy.
      Parameters:
      hierarchy -

    • clearTMACoreMeasurements

      public static void clearTMACoreMeasurements()
      Clear the measurement lists for all TMA core objects in the current hierarchy.

    • clearMeasurements

      public static void clearMeasurements(PathObjectHierarchy hierarchy, Class<? extends PathObject> cls)
      Clear the measurement lists for objects of a specific class in a hierarchy (subclasses are not included!).
      Parameters:
      hierarchy -
      cls -

    • clearMeasurements

      public static void clearMeasurements(Class<? extends PathObject> cls)
      Clear the measurement lists for objects of a specific class in the current hierarchy (subclasses are not included!).
      Parameters:
      cls -

    • clearMeasurements

      public static void clearMeasurements()
      Clear the measurement lists for all detections in the current hierarchy.

    • clearCellMeasurements

      public static void clearCellMeasurements(PathObjectHierarchy hierarchy)
      Clear the measurement lists for all cells in a hierarchy.
      Parameters:
      hierarchy -

    • clearCellMeasurements

      public static void clearCellMeasurements()
      Clear the measurement lists for all cells in the current hierarchy.

    • clearTileMeasurements

      public static void clearTileMeasurements(PathObjectHierarchy hierarchy)
      Clear the measurement lists for all tiles in a hierarchy.
      Parameters:
      hierarchy -

    • clearTileMeasurements

      public static void clearTileMeasurements()
      Clear the measurement lists for all tiles in the current hierarchy.

    • clearRootMeasurements

      public static void clearRootMeasurements(PathObjectHierarchy hierarchy)
      Clear the measurement lists for the root object.
      Parameters:
      hierarchy -

    • clearRootMeasurements

      public static void clearRootMeasurements()
      Clear the measurement lists for the root object.

    • getBasePathClass

      public static PathClass getBasePathClass(PathObject pathObject)
      Get a base class - which is either a valid PathClass which is *not* an intensity class, or else null. This will be null if pathObject.getPathClass() == null. Otherwise, it will be pathObject.getPathClass().getBaseClass() assuming the result isn't an intensity class - or null otherwise.
      Parameters:
      pathObject -
      Returns:

    • getNonIntensityAncestorPathClass

      public static PathClass getNonIntensityAncestorPathClass(PathObject pathObject)
      Get the first ancestor class of pathObject.getPathClass() that is not an intensity class (i.e. not negative, positive, 1+, 2+ or 3+). This will return null if pathClass is null, or if no non-intensity classes are found.
      Parameters:
      pathObject -
      Returns:

    • setIntensityClassifications

      public static void setIntensityClassifications(Collection<? extends PathObject> pathObjects, String measurementName, double... thresholds)
      Set the intensity classifications for the specified objects.
      Parameters:
      pathObjects -
      measurementName - measurement to threshold
      thresholds - either 1 or 3 thresholds, depending upon whether objects should be classified as Positive/Negative or Negative/1+/2+/3+

    • setIntensityClassificationsForSelected

      public static void setIntensityClassificationsForSelected(PathObjectHierarchy hierarchy, String measurementName, double... thresholds)
      Set intensity classifications for all selected (detection) objects in the specified hierarchy.
      Parameters:
      hierarchy -
      measurementName - measurement to threshold
      thresholds - either 1 or 3 thresholds, depending upon whether objects should be classified as Positive/Negative or Negative/1+/2+/3+

    • setIntensityClassifications

      public static void setIntensityClassifications(PathObjectHierarchy hierarchy, Class<? extends PathObject> cls, String measurementName, double... thresholds)
      Set the intensity classifications for objects of the specified class in the specified hierarchy.
      Parameters:
      hierarchy -
      cls -
      measurementName - measurement to threshold
      thresholds - either 1 or 3 thresholds, depending upon whether objects should be classified as Positive/Negative or Negative/1+/2+/3+

    • setIntensityClassifications

      public static void setIntensityClassifications(Class<? extends PathObject> cls, String measurementName, double... thresholds)
      Set the intensity classifications for objects of the specified class in the current hierarchy.
      Parameters:
      cls -
      measurementName - measurement to threshold
      thresholds - either 1 or 3 thresholds, depending upon whether objects should be classified as Positive/Negative or Negative/1+/2+/3+

    • setDetectionIntensityClassifications

      public static void setDetectionIntensityClassifications(PathObjectHierarchy hierarchy, String measurementName, double... thresholds)
      Set the intensity classifications for detections in the specified hierarchy.
      Parameters:
      hierarchy -
      measurementName - measurement to threshold
      thresholds - either 1 or 3 thresholds, depending upon whether objects should be classified as Positive/Negative or Negative/1+/2+/3+

    • setDetectionIntensityClassifications

      public static void setDetectionIntensityClassifications(String measurementName, double... thresholds)
      Set the intensity classifications for detections in the current hierarchy.
      Parameters:
      measurementName - measurement to threshold
      thresholds - either 1 or 3 thresholds, depending upon whether objects should be classified as Positive/Negative or Negative/1+/2+/3+

    • setCellIntensityClassifications

      public static void setCellIntensityClassifications(String measurementName, double... thresholds)
      Set the intensity classifications for cells in the current hierarchy.
      Parameters:
      measurementName - measurement to threshold
      thresholds - either 1 or 3 thresholds, depending upon whether objects should be classified as Positive/Negative or Negative/1+/2+/3+

    • setCellIntensityClassifications

      public static void setCellIntensityClassifications(PathObjectHierarchy hierarchy, String measurementName, double... thresholds)
      Parameters:
      hierarchy -
      measurementName - measurement to threshold
      thresholds - either 1 or 3 thresholds, depending upon whether objects should be classified as Positive/Negative or Negative/1+/2+/3+

    • resetIntensityClassifications

      public static void resetIntensityClassifications(Collection<PathObject> pathObjects)
      Reset the intensity classifications for all specified objects. This means setting the classification to the result of getNonIntensityAncestorPathClass(pathObject)
      Parameters:
      pathObjects -

    • resetIntensityClassifications

      public static void resetIntensityClassifications(PathObjectHierarchy hierarchy)
      Reset the intensity classifications for all detections in the specified hierarchy. This means setting the classification to the result of getNonIntensityAncestorPathClass(pathObject)
      Parameters:
      hierarchy -

    • resetIntensityClassifications

      public static void resetIntensityClassifications()
      Reset the intensity classifications for all detections in the current hierarchy. This means setting the classification to the result of getNonIntensityAncestorPathClass(pathObject)

    • writeImageRegion

      public static void writeImageRegion(ImageServer<BufferedImage> server, RegionRequest request, String path) throws IOException
      Write an image region image to the specified path. The writer will be determined based on the file extension.
      Parameters:
      server -
      request -
      path -
      Throws:
      IOException

    • writePredictionImage

      public static void writePredictionImage(ImageData<BufferedImage> imageData, PixelClassifier classifier, String path) throws IOException
      Write the output of applying a pixel classifier to an image. The writer will be determined based on the file extension.
      Parameters:
      imageData - image to which the classifier should be applied
      classifier - pixel classifier
      path - output file path
      Throws:
      IOException

    • writePredictionImage

      public static void writePredictionImage(String classifierName, String path) throws IOException
      Write the output of applying a pixel classifier to the current image image.
      Parameters:
      classifierName - name of the classifier, see loadPixelClassifier(String)
      path - output file path
      Throws:
      IOException

    • writeDensityMapImage

      public static void writeDensityMapImage(ImageData<BufferedImage> imageData, DensityMaps.DensityMapBuilder densityMap, String path) throws IOException
      Write the output of applying a density map to an image. The writer will be determined based on the file extension.
      Parameters:
      imageData - image to which the classifier should be applied
      densityMap - the density map
      path - output file path
      Throws:
      IOException

    • writeDensityMapImage

      public static void writeDensityMapImage(String densityMapName, String path) throws IOException
      Write the output of applying a density map to the current image image.
      Parameters:
      densityMapName - name of the density map, see loadDensityMap(String)
      path - output file path
      Throws:
      IOException

    • writeImage

      public static void writeImage(ImageServer<BufferedImage> server, String path) throws IOException
      Write a full image to the specified path. The writer will be determined based on the file extension.
      Parameters:
      server -
      path -
      Throws:
      IOException

    • writeImage

      public static void writeImage(BufferedImage img, String path) throws IOException
      Write an image to the specified path. The writer will be determined based on the file extension.
      Parameters:
      img -
      path -
      Throws:
      IOException

    • detectionCentroidDistances

      public static void detectionCentroidDistances(ImageData<?> imageData, boolean splitClassNames)
      Compute the distance for all detection object centroids to the closest detection with each valid, not-ignored classification and add the result to the detection measurement list.
      Parameters:
      imageData -
      splitClassNames -
      See Also:

    • detectionCentroidDistances

      @Deprecated public static void detectionCentroidDistances()
      Deprecated.
      retained only for compatibility of v0.2.0 milestone releases; use instead #detectionCentroidDistances(boolean)
      Compute the distance for all detection object centroids to the closest detection with each valid, not-ignored classification and add the result to the detection measurement list for the current ImageData - without splitting class names.
      See Also:

    • detectionCentroidDistances

      public static void detectionCentroidDistances(boolean splitClassNames)
      Compute the distance for all detection object centroids to the closest detection with each valid, not-ignored classification and add the result to the detection measurement list for the current ImageData.
      Parameters:
      splitClassNames -
      See Also:

    • detectionToAnnotationDistances

      public static void detectionToAnnotationDistances(ImageData<?> imageData, boolean splitClassNames)
      Compute the distance for all detection object centroids to the closest annotation with each valid, not-ignored classification and add the result to the detection measurement list. If the centroid falls inside an annotation, the distance is zero.
      Parameters:
      imageData -
      splitClassNames -
      See Also:

    • detectionToAnnotationDistances

      @Deprecated public static void detectionToAnnotationDistances()
      Deprecated.
      retained only for compatibility of v0.2.0 milestone releases; use instead #detectionToAnnotationDistances(boolean)
      Compute the distance for all detection object centroids to the closest annotation with each valid, not-ignored classification and add the result to the detection measurement list for the current ImageData - without splitting class names.

    • detectionToAnnotationDistances

      public static void detectionToAnnotationDistances(boolean splitClassNames)
      Compute the distance for all detection object centroids to the closest annotation with each valid, not-ignored classification and add the result to the detection measurement list for the current ImageData. If the centroid falls inside an annotation, the distance is zero.
      Parameters:
      splitClassNames -
      See Also:

    • detectionToAnnotationDistancesSigned

      public static void detectionToAnnotationDistancesSigned(ImageData<?> imageData, boolean splitClassNames)
      Compute the signed distance for all detection object centroids to the closest annotation with each valid, not-ignored classification and add the result to the detection measurement list. If the centroid falls inside an annotation, the negative distance to the annotation boundary is used.
      Parameters:
      imageData -
      splitClassNames -
      Since:
      v0.4.0
      See Also:

    • detectionToAnnotationDistancesSigned

      public static void detectionToAnnotationDistancesSigned(boolean splitClassNames)
      Compute the signed distance for all detection object centroids to the closest annotation with each valid, not-ignored classification and add the result to the detection measurement list for the current ImageData. If the centroid falls inside an annotation, the negative distance to the annotation boundary is used.
      Parameters:
      splitClassNames -
      Since:
      v0.4.0
      See Also:

    • setPixelSizeMicrons

      public static boolean setPixelSizeMicrons(ImageData<?> imageData, Number pixelWidthMicrons, Number pixelHeightMicrons, Number zSpacingMicrons)
      Set the metadata for an ImageServer to have the required pixel sizes and z-spacing.

      Returns true if changes were made, false otherwise.

      Parameters:
      imageData -
      pixelWidthMicrons -
      pixelHeightMicrons -
      zSpacingMicrons -
      Returns:
      true if the size was set, false otherwise

    • setPixelSizeMicrons

      public static boolean setPixelSizeMicrons(Number pixelWidthMicrons, Number pixelHeightMicrons, Number zSpacingMicrons)
      Set the metadata for the current ImageData to have the required pixel sizes and z-spacing.

      Returns true if changes were made, false otherwise.

      Parameters:
      pixelWidthMicrons -
      pixelHeightMicrons -
      zSpacingMicrons -
      Returns:
      true if the size was set, false otherwise

    • setPixelSizeMicrons

      public static boolean setPixelSizeMicrons(Number pixelWidthMicrons, Number pixelHeightMicrons)
      Set the metadata for the current ImageData to have the required pixel sizes.

      Returns true if changes were made, false otherwise.

      Parameters:
      pixelWidthMicrons -
      pixelHeightMicrons -
      Returns:
      true if the size was set, false otherwise

    • replaceClassification

      public static void replaceClassification(String originalClassName, String newClassName)
      Apply a new classification to all objects in the current hierarchy with a specified classification.
      Parameters:
      originalClassName - name of the original classification
      newClassName - name of the new classification

    • replaceClassification

      public static void replaceClassification(PathClass originalClass, PathClass newClass)
      Apply a new classification to all objects in the current hierarchy with a specified original classification.
      Parameters:
      originalClass - the original classification
      newClass - the new classification

    • replaceClassification

      public static void replaceClassification(PathObjectHierarchy hierarchy, PathClass originalClass, PathClass newClass)
      Apply a new classification to all objects with a specified original classification in the provided hierarchy.
      Parameters:
      hierarchy - the hierarchy containing the objects
      originalClass - the original classification
      newClass - the new classification

    • replaceClassification

      public static void replaceClassification(Collection<PathObject> pathObjects, PathClass originalClass, PathClass newClass)
      Apply a new classification to all objects with a specified original classification in an object collection.
      Parameters:
      pathObjects -
      originalClass -
      newClass -

    • resolveHierarchy

      public static void resolveHierarchy()
      Resolve the location of annotations in the current hierarchy by setting parent/child relationships.

    • resolveHierarchy

      public static void resolveHierarchy(PathObjectHierarchy hierarchy)
      Resolve the location of annotations in the specified hierarchy by setting parent/child relationships.
      Parameters:
      hierarchy -

    • insertObjects

      public static void insertObjects(Collection<? extends PathObject> pathObjects)
      Insert objects into the hierarchy, resolving their location and setting parent/child relationships.
      Parameters:
      pathObjects -

    • insertObjects

      public static void insertObjects(PathObject pathObject)
      Insert object into the hierarchy, resolving its location and setting parent/child relationships.
      Parameters:
      pathObject -

    • mergePointsForAllClasses

      public static boolean mergePointsForAllClasses()
      Merge point annotations sharing the same PathClass and ImagePlane as the selected annotations of the current hierarchy, creating multi-point annotations for all matching points and removing the (previously-separated) annotations.
      Returns:
      true if changes are made to the hierarchy, false otherwise

    • mergePointsForSelectedObjectClasses

      public static boolean mergePointsForSelectedObjectClasses()
      Merge point annotations sharing the same PathClass and ImagePlane for the current hierarchy, creating multi-point annotations for all matching points and removing the (previously-separated) annotations.
      Returns:
      true if changes are made to the hierarchy, false otherwise

    • splitAllAnnotationAreasByLines

      public static boolean splitAllAnnotationAreasByLines()
      Split annotation objects with area ROIs using dividing lines extracted from annotations objects with line ROIs, then remove the lines from the object hierarchy.

      The new objects will be added to the hierarchy, not inserted. It may therefore be necessary to fall resolveHierarchy(PathObjectHierarchy) afterwards.

      Returns:
      true if changes were made, false otherwise
      Since:
      v0.5.0
      See Also:

    • splitAllAnnotationAreasByLines

      public static boolean splitAllAnnotationAreasByLines(double thickness, boolean removeLines)
      Split annotation objects with area ROIs using dividing lines extracted from annotations objects with line ROIs, with an optional line thickness and optionally removing the dividing lines.

      The new objects will be added to the hierarchy, not inserted. It may therefore be necessary to fall resolveHierarchy(PathObjectHierarchy) afterwards.

      Parameters:
      thickness - the thickness of the line; if greater than zero, the line will be buffered with a radius of half this value
      removeLines - optionally remove the lines after performing the splitting
      Returns:
      true if changes were made, false otherwise
      Since:
      v0.5.0
      See Also:

    • splitAllAnnotationAreasByLines

      public static boolean splitAllAnnotationAreasByLines(PathObjectHierarchy hierarchy)
      Split annotation objects with area ROIs using dividing lines extracted from annotations objects with line ROIs, then remove the lines from the object hierarchy.

      The new objects will be added to the hierarchy, not inserted. It may therefore be necessary to fall resolveHierarchy(PathObjectHierarchy) afterwards.

      Parameters:
      hierarchy - the object hierarchy to use
      Returns:
      true if changes were made, false otherwise
      Since:
      v0.5.0
      See Also:

    • splitAllAnnotationAreasByLines

      public static boolean splitAllAnnotationAreasByLines(PathObjectHierarchy hierarchy, double thickness, boolean removeLines)
      Split annotation objects with area ROIs using dividing lines extracted from annotations objects with line ROIs, with an optional line thickness and optionally removing the dividing lines.

      The new objects will be added to the hierarchy, not inserted. It may therefore be necessary to fall resolveHierarchy(PathObjectHierarchy) afterwards.

      Parameters:
      hierarchy - the object hierarchy to use
      thickness - the thickness of the line; if greater than zero, the line will be buffered with a radius of half this value
      removeLines - optionally remove the lines after performing the splitting
      Returns:
      true if changes were made, false otherwise
      Since:
      v0.5.0
      See Also:

    • splitSelectedAnnotationAreasByLines

      public static boolean splitSelectedAnnotationAreasByLines()
      Split selected annotation objects with area ROIs using dividing lines extracted from annotations objects with line ROIs, then remove the lines from the object hierarchy.

      The new objects will be added to the hierarchy, not inserted. It may therefore be necessary to fall resolveHierarchy(PathObjectHierarchy) afterwards.

      Returns:
      true if changes were made, false otherwise
      Since:
      v0.5.0
      See Also:

    • splitSelectedAnnotationAreasByLines

      public static boolean splitSelectedAnnotationAreasByLines(double thickness, boolean removeLines)
      Split selected annotation objects with area ROIs using dividing lines extracted from annotations objects with line ROIs, with an optional line thickness and optionally removing the dividing lines.

      The new objects will be added to the hierarchy, not inserted. It may therefore be necessary to fall resolveHierarchy(PathObjectHierarchy) afterwards.

      Parameters:
      thickness - the thickness of the line; if greater than zero, the line will be buffered with a radius of half this value
      removeLines - optionally remove the lines after performing the splitting
      Returns:
      true if changes were made, false otherwise
      Since:
      v0.5.0
      See Also:

    • splitSelectedAnnotationAreasByLines

      public static boolean splitSelectedAnnotationAreasByLines(PathObjectHierarchy hierarchy)
      Split selected annotation objects with area ROIs using dividing lines extracted from annotations objects with line ROIs, then remove the lines from the object hierarchy.

      The new objects will be added to the hierarchy, not inserted. It may therefore be necessary to fall resolveHierarchy(PathObjectHierarchy) afterwards.

      Parameters:
      hierarchy - the object hierarchy to use
      Returns:
      true if changes were made, false otherwise
      Since:
      v0.5.0
      See Also:

    • splitSelectedAnnotationAreasByLines

      public static boolean splitSelectedAnnotationAreasByLines(PathObjectHierarchy hierarchy, double thickness, boolean removeLines)
      Split selected annotation objects with area ROIs using dividing lines extracted from annotations objects with line ROIs, with an optional line thickness and optionally removing the dividing lines.

      The new objects will be added to the hierarchy, not inserted. It may therefore be necessary to fall resolveHierarchy(PathObjectHierarchy) afterwards.

      Parameters:
      hierarchy - the object hierarchy to use
      thickness - the thickness of the line; if greater than zero, the line will be buffered with a radius of half this value
      removeLines - optionally remove the lines after performing the splitting
      Returns:
      true if changes were made, false otherwise
      Since:
      v0.5.0
      See Also:

    • splitSpecifiedAreasByLines

      public static boolean splitSpecifiedAreasByLines(PathObjectHierarchy hierarchy, Collection<? extends PathObject> pathObjects, double thickness, boolean removeLines)
      Split the specified objects with area ROIs using dividing lines extracted from specified objects with line ROIs, with an optional line thickness and optionally removing the dividing lines.

      The new objects will be added to the hierarchy, not inserted. It may therefore be necessary to fall resolveHierarchy(PathObjectHierarchy) afterwards.

      Parameters:
      hierarchy - the object hierarchy to use
      pathObjects - the objects to split; usually annotations, but they may be any object except for TMA cores
      thickness - the thickness of the line; if greater than zero, the line will be buffered with a radius of half this value
      removeLines - optionally remove the lines after performing the splitting
      Returns:
      true if changes were made, false otherwise
      Since:
      v0.5.0
      See Also:

    • duplicateSelectedAnnotations

      public static boolean duplicateSelectedAnnotations()
      Duplicate the selected annotations in the current hierarchy.
      Returns:
      true if changes are made to the hierarchy, false otherwise

    • duplicateSelectedAnnotations

      public static boolean duplicateSelectedAnnotations(PathObjectHierarchy hierarchy)
      Duplicate the selected annotations in the specified hierarchy.
      Parameters:
      hierarchy -
      Returns:
      true if changes are made to the hierarchy, false otherwise
      Since:
      v0.4.0

    • copySelectedObjectsToPlane

      public static boolean copySelectedObjectsToPlane(int z, int t)
      Copy the selected objects in the current hierarchy to the specified z-slice and timepoint. This copies only the objects themselves, discarding any parent/child relationships. The copied objects will become the new selection.
      Parameters:
      z - z-slice (0-based index)
      t - timepoint (0-based index)
      Returns:
      true if changes are made to the hierarchy, false otherwise
      Since:
      v0.4.0
      See Also:

    • copySelectedObjectsToPlane

      public static boolean copySelectedObjectsToPlane(ImagePlane plane)
      Copy the selected objects in the current hierarchy to the specified image plane. This copies only the objects themselves, discarding any parent/child relationships. The copied objects will become the new selection.
      Parameters:
      plane -
      Returns:
      true if changes are made to the hierarchy, false otherwise
      Since:
      v0.4.0
      See Also:

    • copySelectedObjectsToPlane

      public static boolean copySelectedObjectsToPlane(PathObjectHierarchy hierarchy, ImagePlane plane)
      Copy the selected objects in the specified hierarchy to the specified image plane. This copies only the objects themselves, discarding any parent/child relationships. The copied objects will become the new selection.
      Parameters:
      hierarchy -
      plane -
      Returns:
      true if changes are made to the hierarchy, false otherwise
      Since:
      v0.4.0

    • copySelectedAnnotationsToPlane

      public static boolean copySelectedAnnotationsToPlane(int z, int t)
      Copy the selected annotations in the current hierarchy to the specified z-slice and timepoint. This copies only the objects themselves, discarding any parent/child relationships. The copied objects will become the new selection.
      Parameters:
      z - z-slice (0-based index)
      t - timepoint (0-based index)
      Returns:
      true if changes are made to the hierarchy, false otherwise
      Since:
      v0.4.0
      See Also:

    • copySelectedAnnotationsToPlane

      public static boolean copySelectedAnnotationsToPlane(ImagePlane plane)
      Copy the selected annotations in the current hierarchy to the specified image plane. This copies only the objects themselves, discarding any parent/child relationships. The copied objects will become the new selection.
      Parameters:
      plane -
      Returns:
      true if changes are made to the hierarchy, false otherwise
      Since:
      v0.4.0
      See Also:

    • copySelectedAnnotationsToPlane

      public static boolean copySelectedAnnotationsToPlane(PathObjectHierarchy hierarchy, ImagePlane plane)
      Copy the selected annotations in the specified hierarchy to the specified image plane. This copies only the objects themselves, discarding any parent/child relationships. The copied objects will become the new selection.
      Parameters:
      hierarchy -
      plane -
      Returns:
      true if changes are made to the hierarchy, false otherwise
      Since:
      v0.4.0

    • mergeAnnotations

      public static boolean mergeAnnotations(Collection<PathObject> annotations)
      Merge annotations for the current hierarchy.
      Parameters:
      annotations - the annotations to merge
      Returns:
      true if changes were made the hierarchy, false otherwise

    • mergeSelectedAnnotations

      public static boolean mergeSelectedAnnotations()
      Merge the currently-selected annotations of the current hierarchy to create a new annotation containing the union of their ROIs.

      Note:

      • The existing annotations will be removed from the hierarchy if possible, therefore should be duplicated first if this is not desired.
      • The new object will be set to be the selected object in the hierarchy (which can be used to retrieve it if needed).
      Returns:
      true if changes are made to the hierarchy, false otherwise

    • mergeAnnotations

      public static boolean mergeAnnotations(PathObjectHierarchy hierarchy, Collection<PathObject> annotations)
      Merge the specified annotations to create a new annotation containing the union of their ROIs.

      Note:

      • The existing annotations will be removed from the hierarchy if possible, therefore should be duplicated first if this is not desired.
      • The new object will be set to be the selected object in the hierarchy (which can be used to retrieve it if needed).
      Parameters:
      hierarchy -
      annotations -
      Returns:
      true if changes are made to the hierarchy, false otherwise

    • mergeSelectedAnnotations

      public static boolean mergeSelectedAnnotations(PathObjectHierarchy hierarchy)
      Merge the currently-selected annotations to create a new annotation containing the union of their ROIs.

      Note:

      • The existing annotations will be removed from the hierarchy if possible, therefore should be duplicated first if this is not desired.
      • The new object will be set to be the selected object in the hierarchy (which can be used to retrieve it if needed).
      Parameters:
      hierarchy -
      Returns:

    • makeInverseAnnotation

      public static boolean makeInverseAnnotation(PathObject pathObject)
      Make an annotation for the current ImageData, for which the ROI is obtained by subtracting the existing ROI from the ROI of its parent object (or entire image if no suitable parent object is available).
      Parameters:
      pathObject - the existing object defining the ROI to invert
      Returns:
      true if an inverted annotation is added to the hierarchy, false otherwise

    • makeInverseAnnotation

      public static boolean makeInverseAnnotation(ImageData<?> imageData, PathObject pathObject)
      Make an annotation for the specified ImageData, for which the ROI is obtained by subtracting the existing ROI from the ROI of its parent object (or entire image if no suitable parent object is available).
      Parameters:
      imageData - the imageData for which an inverted annotation should be created
      pathObject - the existing object defining the ROI to invert
      Returns:
      true if an inverted annotation is added to the hierarchy, false otherwise

    • makeInverseAnnotation

      public static boolean makeInverseAnnotation()
      Make an inverse annotation using the current ImageData and its current selected objects.
      Returns:
      true if an inverted annotation is added to the hierarchy, false otherwise

    • makeInverseAnnotation

      public static boolean makeInverseAnnotation(ImageData<?> imageData)
      Make an inverse annotation using the specified ImageData and current selected objects.
      Parameters:
      imageData - the imageData for which an inverted annotation should be created
      Returns:
      true if an inverted annotation is added to the hierarchy, false otherwise

    • makeInverseAnnotation

      public static boolean makeInverseAnnotation(ImageData<?> imageData, Collection<PathObject> pathObjects)
      Make an annotation, for which the ROI is obtained by subtracting the ROIs of the specified objects from the closest common ancestor ROI (or entire image if the closest ancestor is the root).

      In an inverted annotation can be created, it is added to the hierarchy and set as selected.

      Parameters:
      imageData - the image containing the annotation
      pathObjects - the annotation to invert
      Returns:
      true if an inverted annotation is added to the hierarchy, false otherwise.

    • runObjectClassifier

      public static void runObjectClassifier(String... names) throws IllegalArgumentException
      Apply an object classifier to the current ImageData. This method throws an IllegalArgumentException if the classifier cannot be found.
      Parameters:
      names - the name of the classifier within the current project, or file path to a classifier to load from disk. If more than one name is provided, a composite classifier is created.
      Throws:
      IllegalArgumentException - if the classifier cannot be found

    • runObjectClassifier

      public static void runObjectClassifier(ImageData imageData, String... names) throws IllegalArgumentException
      Apply an object classifier to the specified ImageData. This method throws an IllegalArgumentException if the classifier cannot be found.
      Parameters:
      imageData -
      names - the name of the classifier within the current project, or file path to a classifier to load from disk. If more than one name is provided, a composite classifier is created.
      Throws:
      IllegalArgumentException - if the classifier cannot be found

    • loadObjectClassifier

      public static ObjectClassifier<BufferedImage> loadObjectClassifier(String... names) throws IllegalArgumentException
      Load an object classifier for a project or file path.
      Parameters:
      names - the names of the classifier within the current project, or file paths to a classifier to load from disk. If more than one name is provided, a composite classifier is created (applying each classifier in sequence).
      Returns:
      the requested ObjectClassifier
      Throws:
      IllegalArgumentException - if the classifier cannot be found

    • loadDensityMap

      public static DensityMaps.DensityMapBuilder loadDensityMap(String name) throws IllegalArgumentException
      Load a density map for a project or file path.
      Parameters:
      name - the name of the density map within the current project, or file path to a density map to load from disk.
      Returns:
      the requested DensityMaps.DensityMapBuilder
      Throws:
      IllegalArgumentException - if the density map cannot be found

    • locateFile

      public static String locateFile(String nameOrPath) throws IOException
      Locate a specified file based upon its name or path, with a search depth of 4. This first checks if the provided path is to a file that already exists. If it is not, then it searches recursively within the current project (if available) up to a fixed search depth for a file with the same name.
      Parameters:
      nameOrPath - the original name or path
      Returns:
      the identified file path, or the original file path if no update was found or required
      Throws:
      IOException
      See Also:

    • locateFile

      public static String locateFile(String nameOrPath, int searchDepth) throws IOException
      Locate a specified file based upon its name or path. This first checks if the provided path is to a file that already exists. If it is not, then it searches recursively within the current project (if available) up to a specified search depth for a file with the same name.
      Parameters:
      nameOrPath - the original name or path
      searchDepth - how deep to search subdirectories recursively
      Returns:
      the identified file path, or the original file path if no update was found or required
      Throws:
      IOException
      See Also:

    • findDensityMapHotspots

      public static void findDensityMapHotspots(String densityMapName, int channel, int numHotspots, double minCounts, boolean deleteExisting, boolean peaksOnly) throws IOException
      Find hotspots in a density map for the current image.
      Parameters:
      densityMapName - name of the density map builder, see loadDensityMap(String)
      channel - channel number (usually 0)
      numHotspots - the maximum number of hotspots to generate within each selected object
      minCounts - the minimum value in the 'counts' channel; this is used to avoid generating hotspots in areas with few objects
      deleteExisting - if true, similar annotations will be deleted from the image
      peaksOnly - if true, hotspots will only be generated at intensity peaks in the density map
      Throws:
      IOException

    • findDensityMapHotspots

      public static void findDensityMapHotspots(ImageData<BufferedImage> imageData, String densityMapName, int channel, int numHotspots, double minCounts, boolean deleteExisting, boolean peaksOnly) throws IOException
      Find hotspots in a density map.
      Parameters:
      imageData - the image data
      densityMapName - name of the density map builder, see loadDensityMap(String)
      channel - channel number (usually 0)
      numHotspots - the maximum number of hotspots to generate within each selected object
      minCounts - the minimum value in the 'counts' channel; this is used to avoid generating hotspots in areas with few objects
      deleteExisting - if true, similar annotations will be deleted from the image
      peaksOnly - if true, hotspots will only be generated at intensity peaks in the density map
      Throws:
      IOException

    • findDensityMapHotspots

      public static void findDensityMapHotspots(ImageData<BufferedImage> imageData, DensityMaps.DensityMapBuilder densityMap, int channel, int numHotspots, double minCounts, boolean deleteExisting, boolean peaksOnly) throws IOException
      Find hotspots in a density map.
      Parameters:
      imageData - the image data
      densityMap - builder to generate a density map
      channel - channel number (usually 0)
      numHotspots - the maximum number of hotspots to generate within each selected object
      minCounts - the minimum value in the 'counts' channel; this is used to avoid generating hotspots in areas with few objects
      deleteExisting - if true, similar annotations will be deleted from the image
      peaksOnly - if true, hotspots will only be generated at intensity peaks in the density map
      Throws:
      IOException

    • createAnnotationsFromDensityMap

      public static void createAnnotationsFromDensityMap(String densityMapName, Map<Integer,? extends Number> thresholds, String pathClassName, String... options) throws IOException
      Create annotations from a density map for the current image.
      Parameters:
      densityMapName - the name of the density map within the current project, or file path to a density map to load from disk
      thresholds - map between channels to threshold (zero-based index) and thresholds to apply
      pathClassName - name of the classification for the annotations that will be created
      options - additional options when creating the annotations
      Throws:
      IOException
      See Also:

    • createAnnotationsFromDensityMap

      public static void createAnnotationsFromDensityMap(ImageData<BufferedImage> imageData, String densityMapName, Map<Integer,? extends Number> thresholds, String pathClassName, String... options) throws IOException
      Create annotations from a density map for the specified image.
      Parameters:
      imageData - image for which the density map should be generated
      densityMapName - the name of the density map within the current project, or file path to a density map to load from disk
      thresholds - map between channels to threshold (zero-based index) and thresholds to apply
      pathClassName - name of the classification for the annotations that will be created
      options - additional options when creating the annotations
      Throws:
      IOException
      See Also:

    • createAnnotationsFromDensityMap

      public static void createAnnotationsFromDensityMap(ImageData<BufferedImage> imageData, DensityMaps.DensityMapBuilder densityMap, Map<Integer,? extends Number> thresholds, String pathClassName, PixelClassifierTools.CreateObjectOptions... options) throws IOException
      Create annotations from a density map for the specified image.
      Parameters:
      imageData - image to which the density map corresponds
      densityMap - the density map to use
      thresholds - map between channels to threshold (zero-based index) and thresholds to apply
      pathClassName - name of the classification for the annotations that will be created
      options - additional options when creating the annotations
      Throws:
      IOException
      See Also:

    • getLogger

      public static org.slf4j.Logger getLogger()
      Get the logger associated with this class.
      Returns:

    • loadPixelClassifier

      public static PixelClassifier loadPixelClassifier(String name) throws IllegalArgumentException
      Load a pixel classifier for a project or file path.
      Parameters:
      name - the name of the classifier within the current project, or file path to a classifier to load from disk.
      Returns:
      the requested PixelClassifier
      Throws:
      IllegalArgumentException - if the classifier cannot be found

    • addPixelClassifierMeasurements

      public static void addPixelClassifierMeasurements(String classifierName, String measurementID)
      Add measurements from pixel classification to the selected objects.
      Parameters:
      classifierName - the pixel classifier name
      measurementID -
      See Also:

    • addPixelClassifierMeasurements

      public static void addPixelClassifierMeasurements(PixelClassifier classifier, String measurementID)
      Add measurements from pixel classification to the selected objects.
      Parameters:
      classifier - the pixel classifier
      measurementID -

    • createDetectionsFromPixelClassifier

      public static void createDetectionsFromPixelClassifier(String classifierName, double minArea, double minHoleArea, String... options) throws IllegalArgumentException, IOException
      Create detection objects based upon the output of a pixel classifier, applied to selected objects. If no objects are selected, objects are created across the entire image.
      Parameters:
      classifierName - the name of the pixel classifier
      minArea - the minimum area of connected regions to retain
      minHoleArea - the minimum area of connected 'hole' regions to retain
      options - additional options to control how objects are created
      Throws:
      IOException
      IllegalArgumentException
      See Also:

    • createDetectionsFromPixelClassifier

      public static void createDetectionsFromPixelClassifier(PixelClassifier classifier, double minArea, double minHoleArea, String... options) throws IOException
      Create detection objects based upon the output of a pixel classifier, applied to selected objects. If no objects are selected, objects are created across the entire image.
      Parameters:
      classifier - the pixel classifier
      minArea - the minimum area of connected regions to retain
      minHoleArea - the minimum area of connected 'hole' regions to retain
      options - additional options to control how objects are created
      Throws:
      IOException

    • createAnnotationsFromPixelClassifier

      public static void createAnnotationsFromPixelClassifier(String classifierName, double minArea, double minHoleArea, String... options) throws IllegalArgumentException, IOException
      Create annotation objects based upon the output of a pixel classifier, applied to selected objects. If no objects are selected, objects are created across the entire image.
      Parameters:
      classifierName - the name of the pixel classifier
      minArea - the minimum area of connected regions to retain
      minHoleArea - the minimum area of connected 'hole' regions to retain
      options - additional options to control how objects are created
      Throws:
      IOException
      IllegalArgumentException
      See Also:

    • createAnnotationsFromPixelClassifier

      public static void createAnnotationsFromPixelClassifier(PixelClassifier classifier, double minArea, double minHoleArea, String... options) throws IOException
      Create annotation objects based upon the output of a pixel classifier, applied to selected objects. If no objects are selected, objects are created across the entire image.
      Parameters:
      classifier - the pixel classifier
      minArea - the minimum area of connected regions to retain
      minHoleArea - the minimum area of connected 'hole' regions to retain
      options - additional options to control how objects are created
      Throws:
      IOException

    • classifyDetectionsByCentroid

      public static void classifyDetectionsByCentroid(PixelClassifier classifier)
      Classify detections according to the prediction of the pixel corresponding to the detection centroid using a PixelClassifier. If the detections are cells, the nucleus ROI is used where possible.
      Parameters:
      classifier - the pixel classifier

    • classifyDetectionsByCentroid

      public static void classifyDetectionsByCentroid(String classifierName)
      Classify detections according to the prediction of the pixel corresponding to the detection centroid using a PixelClassifier. If the detections are cells, the nucleus ROI is used where possible.
      Parameters:
      classifierName - name of the pixel classifier

    • checkMinVersion

      public static void checkMinVersion(String version) throws UnsupportedOperationException
      Check whether the current QuPath version is ≥ the specified version. This can be added at the beginning of a script to prevent the script running if it is known to be incompatible.

      It throws an exception if the test is failed so that it can be added in a single line, with the script stopping if the criterion is not met.

      Using this successfully depends upon VERSION being available. To avoid an exception if it is not, use 

      
 if (VERSION != null)
   checkMinVersion("0.4.0");
      Parameters:
      version - last known compatible version (inclusive)
      Throws:
      UnsupportedOperationException - if the version test is not passed, of version information is unavailable
      Since:
      v0.4.0
      See Also:

    • checkVersionRange

      public static void checkVersionRange(String minVersion, String maxVersion) throws UnsupportedOperationException
      Check whether the current QuPath version is ≥ the specified minimum version, and < the specified maximum. This can be added at the beginning of a script to prevent the script running if it is known to be incompatible.

      The minimum is inclusive and maximum is exclusive so that the maximum can be given as the first version known to introduce a breaking change.

      Using this successfully depends upon VERSION being available. To avoid an exception if it is not, use 

      
 if (VERSION != null)
   checkVersionRange("0.4.0", "0.5.0");
      Parameters:
      minVersion - last known compatible version (inclusive)
      maxVersion - next known incompatible version
      Throws:
      UnsupportedOperationException - if the version test is not passed, of version information is unavailable
      Since:
      v0.4.0
      See Also:

    • removeObjectsOutsideImage

      public static boolean removeObjectsOutsideImage()
      Remove objects that are entirely outside the current image.
      Returns:
      true if objects were removed, false otherwise
      Since:
      v0.4.0
      See Also:

    • removeObjectsOutsideImage

      public static boolean removeObjectsOutsideImage(boolean ignoreIntersecting)
      Remove objects that are entirely or partially outside the current image.
      Parameters:
      ignoreIntersecting - if true, ignore objects that are intersecting the image bounds; if false, remove these intersecting objects too
      Returns:
      true if objects were removed, false otherwise
      Since:
      v0.4.0
      See Also:

    • removeObjectsOutsideImage

      public static boolean removeObjectsOutsideImage(ImageData<?> imageData)
      Remove objects that are entirely or outside the specified image.
      Parameters:
      imageData - the image data, including a hierarchy and server to use
      Returns:
      true if objects were removed, false otherwise
      Since:
      v0.4.0
      See Also:

    • removeObjectsOutsideImage

      public static boolean removeObjectsOutsideImage(ImageData<?> imageData, boolean ignoreIntersecting)
      Remove objects that are entirely or partially outside the specified image.
      Parameters:
      imageData - the image data, including a hierarchy and server to use
      ignoreIntersecting - if true, ignore objects that are intersecting the image bounds; if false, remove these intersecting objects too
      Returns:
      true if objects were removed, false otherwise
      Since:
      v0.4.0
      See Also:

    • removeOrClipObjectsOutsideImage

      public static boolean removeOrClipObjectsOutsideImage()
      Remove objects occurring outside the current image bounds, clipping annotations where possible to retain the part that is inside the image.
      Returns:
      true if changes were made, false otherwise
      Since:
      v0.4.0
      See Also:

    • removeOrClipObjectsOutsideImage

      public static boolean removeOrClipObjectsOutsideImage(ImageData<?> imageData)
      Remove objects occurring outside the specified image bounds, clipping annotations where possible to retain the part that is inside the image.
      Parameters:
      imageData -
      Returns:
      true if changes were made, false otherwise
      Since:
      v0.4.0
      See Also: