Package qupath.lib.objects

Class PathObject

java.lang.Object
qupath.lib.objects.PathObject
All Implemented Interfaces:
Externalizable, Serializable
Direct Known Subclasses:
PathROIObject, PathRootObject
public abstract class PathObject extends Object implements Externalizable
Fundamental object of interest in QuPath.

Used as a base class for annotations, detections, cells, TMA cores, tiles...

Author:
Pete Bankhead
See Also:

  • Constructor Details

    • PathObject

      public PathObject(MeasurementList measurements)
      Create a PathObject with a specific measurement list.

      This can be used e.g. to create an object with a more memory-efficient list, at the cost of generality/mutability.

      Parameters:
      measurements -

    • PathObject

      public PathObject()
      Default constructor. Used for Externalizable support, not intended to be used by other consumers.

  • Method Details

    • getParent

      public PathObject getParent()
      Request the parent object. Each PathObject may have only one parent.
      Returns:

    • setLocked

      public void setLocked(boolean locked)
      Set locked status, if possible.

      Subclasses should override this method to support locking or unlocking. Default implementation throws an UnsupportedOperationException if an attempt is made to unlock the object.

      Parameters:
      locked -

    • isLocked

      public boolean isLocked()
      Query the locked status.

      Subclasses should override this method to support locking or unlocking. Default implementation always returns true.

      Returns:
      true if the object is locked and should not be modified.

    • getLevel

      public int getLevel()
      The level of the object in a hierarchy.

      If the object has no parent, this is 0. Otherwise, it is equal to parent.getLevel() + 1.

      Returns:

    • isRootObject

      public boolean isRootObject()
      Returns true if the object is the 'root' of an object hierarchy.
      Returns:
      See Also:

    • getMeasurementList

      public MeasurementList getMeasurementList()
      Retrieve the list stored measurements for the object.

      This can be used to query or add specific numeric measurements.

      Returns:

    • getMeasurements

      public Map<String,Number> getMeasurements()
      Get a map-based view on getMeasurementList(). This is likely to be less efficient (because it does not support primitives), but has several advantages
      • it uses a familiar and standard API
      • it is much more amenable for scripting, especially in Groovy
      • it is possible to return null for missing values, rather than only Double.NaN
      The MeasurementList is retained for backwards-compatibility, particularly the ability to read older data files. Changes made to the map are propagated through to the MeasurementList, so it should be possible to use them interchangeably - however note that there may be some loss of precision if the backing measurement list uses floats rather than doubles.

      It is possible that a map implementation becomes the standard in the future and getMeasurementList() may be deprecated; this is an experimental feature introduced in v0.4.0 for testing.

      Returns:
      Since:
      v0.4.0

    • createEmptyMeasurementList

      protected MeasurementList createEmptyMeasurementList()
      Create a new MeasurementList of the preferred type for this object.

      This will be called whenever a MeasurementList is requested, if one is not already stored.

      Subclasses can use this method to create more efficient MeasurementList implementations if required.

      Returns:

    • objectCountPostfix

      protected String objectCountPostfix()

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • addChildObject

      public void addChildObject(PathObject pathObject)
      Add an object to the child list of this object.
      Parameters:
      pathObject -
      Since:
      v0.4.0

    • addPathObject

      @Deprecated public void addPathObject(PathObject pathObject)
      Deprecated.
      since v0.4.0, replaced by addChildObject(PathObject)
      Legacy method to add a single child object.
      Parameters:
      pathObject -

    • addChildObjects

      public void addChildObjects(Collection<? extends PathObject> pathObjects)
      Add a collection of objects to the child list of this object.
      Parameters:
      pathObjects -
      Since:
      v0.4.0

    • addPathObjects

      @Deprecated public void addPathObjects(Collection<? extends PathObject> pathObjects)
      Deprecated.
      since v0.4.0, replaced by addChildObjects(Collection)
      Legacy method to add child objects.
      Parameters:
      pathObjects -

    • removeChildObject

      public void removeChildObject(PathObject pathObject)
      Remove a single object from the child list of this object.
      Parameters:
      pathObject -
      Since:
      v0.4.0

    • removePathObject

      @Deprecated public void removePathObject(PathObject pathObject)
      Deprecated.
      since v0.4.0, replaced by removeChildObject(PathObject)
      Legacy method to remove a single child object.
      Parameters:
      pathObject -

    • removeChildObjects

      public void removeChildObjects(Collection<PathObject> pathObjects)
      Remove multiple objects from the child list of this object.
      Parameters:
      pathObjects -
      Since:
      v0.4.0

    • removePathObjects

      @Deprecated public void removePathObjects(Collection<PathObject> pathObjects)
      Deprecated.
      since v0.4.0, replaced by removeChildObjects(Collection)
      Legacy method to remove specified child objects.
      Parameters:
      pathObjects -

    • clearChildObjects

      public void clearChildObjects()
      Remove all child objects.
      Since:
      v0.4.0

    • clearPathObjects

      @Deprecated public void clearPathObjects()
      Deprecated.
      since v0.4.0, replaced by clearChildObjects()
      Legacy method to remove all child objects.

    • nChildObjects

      public int nChildObjects()
      Total number of child objects. Note that this is the size of the child object list - it does not check descendants recursively.
      Returns:
      the number of direct child objects
      See Also:

    • nDescendants

      public int nDescendants()
      Total number of descendant objects. This involves counting objects recursively; to get the number of direct child object only see nChildObjects().
      Returns:
      the number of child objects, plus the number of each child object's descendants
      See Also:

    • hasChildObjects

      public boolean hasChildObjects()
      Check if this object has children, or if its child object list is empty.
      Returns:
      Since:
      v0.4.0, replaces hasChildren() for more consistent naming

    • hasChildren

      @Deprecated public boolean hasChildren()
      Deprecated.
      since v0.4.0, replaced by hasChildObjects()
      Legacy method to check for child objects.
      Returns:

    • hasROI

      public boolean hasROI()
      Returns true if this object has a ROI.

      In general, objects are expected to have ROIs unless they are root objects.

      Returns:

    • isAnnotation

      public boolean isAnnotation()
      Returns true if the object is an annotation.
      Returns:
      See Also:

    • isDetection

      public boolean isDetection()
      Returns true if the object is a detection.

      Note that this returns true also if the object is a subclass of a detection, e.g. a tile or cell.

      Returns:
      See Also:

    • isCell

      public boolean isCell()
      Returns true if the object is a cell object (a special type of detection, which can contain second ROI for the nucleus).
      Returns:
      See Also:

    • hasMeasurements

      public boolean hasMeasurements()
      Returns true if the measurement list for this object is not empty.
      Returns:

    • isTMACore

      public boolean isTMACore()
      Returns true if this object represents a TMA core.
      Returns:
      See Also:

    • isTile

      public boolean isTile()
      Returns true if this object represents an image tile.
      Returns:
      See Also:

    • isEditable

      public abstract boolean isEditable()
      Flag indicating that the object is editable.

      If this returns false, this indicates the object has a ROI this should not be moved or resized (e.g. because child objects depend upon it).

      Returns:

    • getChildObjects

      public Collection<PathObject> getChildObjects()
      Get a collection of child objects.

      In the current implementation, this is immutable - it cannot be modified directly.

      Returns:

    • getChildObjects

      public Collection<PathObject> getChildObjects(Collection<PathObject> children)
      Get a collection containing all child objects.
      Parameters:
      children - optional collection to which the children should be added
      Returns:
      collection containing all child object (the same as children if provided)

    • getDescendantObjects

      public Collection<PathObject> getDescendantObjects(Collection<PathObject> descendants)
      Get a collection containing all descendant objects.
      Parameters:
      descendants - optional collection to which the descendants should be added
      Returns:
      collection containing all descendant object (the same as descendants if provided)

    • getChildObjectsAsArray

      public PathObject[] getChildObjectsAsArray()
      Get a defensive copy of child objects as an array.

      Why? Well perhaps you want to iterate through it and getChildObjects() may result in synchronization problems if the list is modified by another thread. In such a case a defensive copy may already be required, and it is more efficient to request it here.

      Returns:

    • getPathClass

      public abstract PathClass getPathClass()
      Get the classification of the object.
      Returns:

    • setPathClass

      public void setPathClass(PathClass pc)
      Set the classification of the object, without specifying any classification probability.
      Parameters:
      pc -

    • resetPathClass

      public boolean resetPathClass()
      Reset the classification (i.e. set it to null).
      Returns:
      true if the classification has changed, false otherwise (i.e. it was already null)

    • setClassifications

      public void setClassifications(Collection<String> classifications)
      Set the PathClass from a collection of names according to the rules:
      • If the collection is empty, reset the PathClass
      • If the collection has one element, set it to be the name of the PathClass
      • If the collection has multiple element, create and set a derived PathClass with each unique element the name of a PathClass component
      The uniqueness is equivalent to copying the elements into a set; if a set is provided as input then a defensive copy will be made..

      Ultimately, a single PathClass object is created to encapsulate the classification and the color used for display - but setClassifications(Collection) and getClassifications() provides a different (complementary) way to think of classifications within QuPath.

      Important: This is an experimental feature introduced in QuPath v0.4.0 to provide an alternative way to interact with classifications and to add support for multiple classifications. It is possible that this becomes the 'standard' approach in future versions, with PathClass being deprecated.

      Feedback or discussion on the approach is welcome on the forum at image.sc.

      Parameters:
      classifications -
      Since:
      v0.4.0
      See Also:

    • getClassifications

      public Set<String> getClassifications()
      Get the components of the PathClass as an unmodifiable set. Important: This is an experimental feature introduced in QuPath v0.4.0 to provide an alternative way to interact with classifications and to add support for multiple classifications. It is possible that this becomes the 'standard' approach in future versions, with PathClass being deprecated.

      Feedback or discussion on the approach is welcome on the forum at image.sc.

      Returns:
      an empty collection is the PathClass is null, otherwise a collection of strings where each string gives the name of one component of the PathClass
      Since:
      v0.4.0
      See Also:

    • setPathClass

      public abstract void setPathClass(PathClass pathClass, double classProbability)
      Set the classification of the object, specifying a classification probability.

      The probability is expected to be between 0 and 1, or Double.NaN if no probability should be set.

      Parameters:
      pathClass -
      classProbability -

    • getClassProbability

      public abstract double getClassProbability()
      Request the classification probability, or Double.NaN if no probability is available.
      Returns:

    • getDisplayedName

      public String getDisplayedName()
      Request an object name in a form suitable for displaying.

      This may combine various properties of the object.

      Returns:

    • getName

      public String getName()
      Request the stored object name.
      Returns:

    • setName

      public void setName(String name)
      Set the stored object name.
      Parameters:
      name -

    • getROI

      public abstract ROI getROI()
      Get the region of interest (ROI) for the object.
      Returns:

    • getColor

      public Integer getColor()
      Return any stored color as a packed RGB value.

      This may be null if no color has been set.

      Returns:
      Since:
      v0.4.0
      See Also:

    • getColorRGB

      @Deprecated public Integer getColorRGB()
      Deprecated.
      since v0.4.0, use getColor() instead.
      Return any stored color as a packed RGB value.

      This may be null if no color has been set

      Returns:

    • setColorRGB

      @Deprecated public void setColorRGB(Integer color)
      Deprecated.
      since v0.4.0, use setColor(Integer) instead.
      Set the display color.
      Parameters:
      color -

    • setColor

      public void setColor(Integer color)
      Set the display color as a packed (A)RGB integer (alpha may not be used by viewing code).
      Parameters:
      color - packed (A)RGB value, or null if a color should not stored
      Since:
      v0.4.0
      See Also:

    • setColor

      public void setColor(int red, int green, int blue)
      Set the display color as 8-bit RGB values
      Parameters:
      red -
      green -
      blue -
      Since:
      v0.4.0

    • getID

      public UUID getID()
      Get the ID for this object.
      Returns:
      See Also:

    • setID

      public void setID(UUID id) throws IllegalArgumentException
      Set the ID for this object.

      Important! Use this with caution or, even better, not at all!

      In general, the ID for an object should be unique. This is best achieved by allowing the ID to be generated randomly when the object is created, and never changing it to anything else.

      However, there are times when it is necessary to transfer the ID from an existing object, such as whenever the ROI of an object is being transformed and the original object deleted.

      For that reason, it is possible (although discouraged) to set an ID explicitly.

      Parameters:
      id - the ID to use
      Throws:
      IllegalArgumentException - if the specified ID is null

    • refreshID

      public void refreshID()
      Regenerate a new random ID.
      See Also:

    • storeMetadataValue

      protected Object storeMetadataValue(String key, String value)
      Store a metadata value.

      Note: This should be used with caution; for objects that could be plentiful (e.g. detections) it is likely to be unwise to store any metadata values, since these can't be stored particularly efficiently - and therefore this could lead to far too high memory requirements.

      If metadata is never stored for an object, no storage object is created - only a null reference.

      Therefore the intention is that some newly-defined PathObject classes may take advantage of this mechanism and expose their own API for getting/setting values, backed-up by this store (which takes care of serialization/deserialization). However class definitions can also avoid making any use of this whatsoever if it's expected that it could lead to too much memory being required.

      Parameters:
      key -
      value -
      Returns:
      See Also:

    • retrieveMetadataValue

      protected Object retrieveMetadataValue(String key)
      Get a metadata value.
      Parameters:
      key -
      Returns:
      the metadata value if set, or null if not
      See Also:

    • retrieveMetadataKeys

      protected Set<String> retrieveMetadataKeys()
      Get the set of metadata keys.
      Returns:

    • getUnmodifiableMetadataMap

      protected Map<String,String> getUnmodifiableMetadataMap()
      Get an unmodifiable map of the metadata.
      Returns:

    • clearMetadataMap

      protected void clearMetadataMap()
      Remove all stored metadata values.

    • getMetadata

      public Map<String,String> getMetadata()
      Get a key/value pair map for object metadata.
      Returns:
      Since:
      v0.5.0

    • writeExternal

      public void writeExternal(ObjectOutput out) throws IOException
      Specified by:
      writeExternal in interface Externalizable
      Throws:
      IOException

    • readExternal

      public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
      Specified by:
      readExternal in interface Externalizable
      Throws:
      IOException
      ClassNotFoundException