Class PathObject
- All Implemented Interfaces:
Externalizable,Serializable
- Direct Known Subclasses:
PathROIObject,PathRootObject
Used as a base class for annotations, detections, cells, TMA cores, tiles...
- Author:
- Pete Bankhead
- See Also:
-
Constructor Summary
ConstructorsConstructorDescriptionDefault constructor.PathObject(MeasurementList measurements) Create a PathObject with a specific measurement list. -
Method Summary
Modifier and TypeMethodDescriptionvoidaddChildObject(PathObject pathObject) Add an object to the child list of this object.voidaddChildObjects(Collection<? extends PathObject> pathObjects) Add a collection of objects to the child list of this object.voidaddPathObject(PathObject pathObject) Deprecated.voidaddPathObjects(Collection<? extends PathObject> pathObjects) Deprecated.since v0.4.0, replaced byaddChildObjects(Collection)voidRemove all child objects.protected voidRemove all stored metadata values.voidDeprecated.since v0.4.0, replaced byclearChildObjects()protected MeasurementListCreate a new MeasurementList of the preferred type for this object.Get a collection of child objects.getChildObjects(Collection<PathObject> children) Get a collection containing all child objects.Get a defensive copy of child objects as an array.Get the components of thePathClassas an unmodifiable set.abstract doubleRequest the classification probability, or Double.NaN if no probability is available.getColor()Return any stored color as a packed RGB value.Deprecated.since v0.4.0, usegetColor()instead.getDescendantObjects(Collection<PathObject> descendants) Get a collection containing all descendant objects.Request an object name in a form suitable for displaying.getID()Get the ID for this object.intgetLevel()The level of the object in a hierarchy.Retrieve the list stored measurements for the object.Get a map-based view ongetMeasurementList().Get a key/value pair map for object metadata.getName()Request the stored object name.Request the parent object.abstract PathClassGet the classification of the object.abstract ROIgetROI()Get the region of interest (ROI) for the object.Get an unmodifiable map of the metadata.booleanCheck if this object has children, or if its child object list is empty.booleanDeprecated.since v0.4.0, replaced byhasChildObjects()booleanReturns true if the measurement list for this object is not empty.booleanhasROI()Returns true if this object has a ROI.booleanReturns true if the object is an annotation.booleanisCell()Returns true if the object is a cell object (a special type of detection, which can contain second ROI for the nucleus).booleanReturns true if the object is a detection.abstract booleanFlag indicating that the object is editable.booleanisLocked()Query the locked status.booleanReturns true if the object is the 'root' of an object hierarchy.booleanisTile()Returns true if this object represents an image tile.booleanReturns true if this object represents a TMA core.intTotal number of child objects.intTotal number of descendant objects.protected StringvoidvoidRegenerate a new random ID.voidremoveChildObject(PathObject pathObject) Remove a single object from the child list of this object.voidremoveChildObjects(Collection<PathObject> pathObjects) Remove multiple objects from the child list of this object.voidremovePathObject(PathObject pathObject) Deprecated.since v0.4.0, replaced byremoveChildObject(PathObject)voidremovePathObjects(Collection<PathObject> pathObjects) Deprecated.since v0.4.0, replaced byremoveChildObjects(Collection)booleanReset the classification (i.e.Get the set of metadata keys.protected ObjectGet a metadata value.voidsetClassifications(Collection<String> classifications) Set thePathClassfrom 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..voidsetColor(int red, int green, int blue) Set the display color as 8-bit RGB valuesvoidSet the display color as a packed (A)RGB integer (alpha may not be used by viewing code).voidsetColorRGB(Integer color) Deprecated.since v0.4.0, usesetColor(Integer)instead.voidSet the ID for this object.voidsetLocked(boolean locked) Set locked status, if possible.voidSet the stored object name.voidSet the classification of the object, without specifying any classification probability.abstract voidsetPathClass(PathClass pathClass, double classProbability) Set the classification of the object, specifying a classification probability.protected ObjectstoreMetadataValue(String key, String value) Store a metadata value.toString()void
-
Constructor Details
-
PathObject
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
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
UnsupportedOperationExceptionif 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
Retrieve the list stored measurements for the object.This can be used to query or add specific numeric measurements.
- Returns:
-
getMeasurements
Get a map-based view ongetMeasurementList(). 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
nullfor missing values, rather than onlyDouble.NaN
MeasurementListis retained for backwards-compatibility, particularly the ability to read older data files. Changes made to the map are propagated through to theMeasurementList, 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
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
-
toString
-
addChildObject
Add an object to the child list of this object.- Parameters:
pathObject-- Since:
- v0.4.0
-
addPathObject
Deprecated.since v0.4.0, replaced byaddChildObject(PathObject)Legacy method to add a single child object.- Parameters:
pathObject-
-
addChildObjects
Add a collection of objects to the child list of this object.- Parameters:
pathObjects-- Since:
- v0.4.0
-
addPathObjects
Deprecated.since v0.4.0, replaced byaddChildObjects(Collection)Legacy method to add child objects.- Parameters:
pathObjects-
-
removeChildObject
Remove a single object from the child list of this object.- Parameters:
pathObject-- Since:
- v0.4.0
-
removePathObject
Deprecated.since v0.4.0, replaced byremoveChildObject(PathObject)Legacy method to remove a single child object.- Parameters:
pathObject-
-
removeChildObjects
Remove multiple objects from the child list of this object.- Parameters:
pathObjects-- Since:
- v0.4.0
-
removePathObjects
Deprecated.since v0.4.0, replaced byremoveChildObjects(Collection)Legacy method to remove specified child objects.- Parameters:
pathObjects-
-
clearChildObjects
public void clearChildObjects()Remove all child objects.- Since:
- v0.4.0
-
clearPathObjects
Deprecated.since v0.4.0, replaced byclearChildObjects()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 seenChildObjects().- 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.since v0.4.0, replaced byhasChildObjects()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
Get a collection of child objects.In the current implementation, this is immutable - it cannot be modified directly.
- Returns:
-
getChildObjects
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
childrenif provided)
-
getDescendantObjects
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
descendantsif provided)
-
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
Get the classification of the object.- Returns:
-
setPathClass
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
Set thePathClassfrom 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
Ultimately, a single
PathClassobject is created to encapsulate the classification and the color used for display - butsetClassifications(Collection)andgetClassifications()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
PathClassbeing deprecated.Feedback or discussion on the approach is welcome on the forum at image.sc.
- Parameters:
classifications-- Since:
- v0.4.0
- See Also:
-
getClassifications
Get the components of thePathClassas 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, withPathClassbeing 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
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
Request an object name in a form suitable for displaying.This may combine various properties of the object.
- Returns:
-
getName
Request the stored object name.- Returns:
-
setName
Set the stored object name.- Parameters:
name-
-
getROI
Get the region of interest (ROI) for the object.- Returns:
-
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.since v0.4.0, usegetColor()instead.Return any stored color as a packed RGB value.This may be null if no color has been set
- Returns:
-
setColorRGB
Deprecated.since v0.4.0, usesetColor(Integer)instead.Set the display color.- Parameters:
color-
-
setColor
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
Get the ID for this object.- Returns:
- See Also:
-
setID
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
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
Get a metadata value.- Parameters:
key-- Returns:
- the metadata value if set, or null if not
- See Also:
-
retrieveMetadataKeys
Get the set of metadata keys.- Returns:
-
getUnmodifiableMetadataMap
Get an unmodifiable map of the metadata.- Returns:
-
clearMetadataMap
protected void clearMetadataMap()Remove all stored metadata values. -
getMetadata
Get a key/value pair map for object metadata.- Returns:
- Since:
- v0.5.0
-
writeExternal
- Specified by:
writeExternalin interfaceExternalizable- Throws:
IOException
-
readExternal
- Specified by:
readExternalin interfaceExternalizable- Throws:
IOExceptionClassNotFoundException
-
addChildObject(PathObject)