Package qupath.imagej.tools

Class IJTools

java.lang.Object
qupath.imagej.tools.IJTools
public class IJTools extends Object
Collection of static methods to help with using ImageJ with QuPath.
Author:
Pete Bankhead

  • Constructor Details

    • IJTools

      public IJTools()

  • Method Details

    • setMemoryThreshold

      public static void setMemoryThreshold(double threshold)
      Parameters:
      threshold - - value in the interval ]0;1] defining the maximum remaining memory fraction an image can have when importing an image to ImageJ

    • isMemorySufficient

      public static boolean isMemorySufficient(RegionRequest region, ImageData<BufferedImage> imageData) throws Exception
      Check if sufficient memory is available to request pixels for a specific region, and the number of pixels is less than the maximum length of a Java array.
      Parameters:
      region - the requested region coming from
      imageData - this BufferedImage
      Returns:
      true if the memory is sufficient
      Throws:
      Exception - either the fact that ImageJ cannot handle the image size or that the memory is insufficient

    • extractHyperstack

      public static ImagePlus extractHyperstack(ImageServer<BufferedImage> server, RegionRequest request) throws IOException
      Extract a full ImageJ hyperstack for a specific region, using all z-slices and time points.
      Parameters:
      server -
      request -
      Returns:
      Throws:
      IOException

    • extractHyperstack

      public static ImagePlus extractHyperstack(ImageServer<BufferedImage> server, RegionRequest request, int zStart, int zEnd, int tStart, int tEnd) throws IOException
      Extract a full ImageJ hyperstack for a specific region, for specified ranges of z-slices and time points.
      Parameters:
      server - server from which to extract pixels
      request - region and downsample value; if null, the entire image is used
      zStart - starting z-slice index (0-based index)
      zEnd - ending z-slice index (exclusive)
      tStart - starting timepoint index (0-based index)
      tEnd - ending timepoint index (exclusive)
      Returns:
      the ImageJ hyperstack
      Throws:
      IOException

    • convertToFloatProcessor

      public static ImageProcessor convertToFloatProcessor(SimpleImage image)
      Convert a SimpleImage to an ImageProcessor.
      Parameters:
      image -
      Returns:

    • setTitleFromObject

      public static void setTitleFromObject(PathImage<ImagePlus> pathImage, PathObject pathObject)
      Set the name of an image based on a PathObject.

      Useful whenever the ROI for an object is being extracted for display separately.

      Parameters:
      pathImage -
      pathObject -

    • calibrateImagePlus

      public static void calibrateImagePlus(ImagePlus imp, RegionRequest request, ImageServer<BufferedImage> server)
      Set an ImagePlus's Calibration and FileInfo properties based on a RegionRequest and PathImageServer. It is assumed at the image contained in the ImagePlus has been correctly read from the server.
      Parameters:
      imp -
      request -
      server -

    • estimateDownsampleFactor

      public static double estimateDownsampleFactor(ImagePlus imp, ImageServer<?> server)
      Estimate the downsample factor for an image region extracted from an image server, based upon the ratio of pixel sizes if possible or ratio of dimensions if necessary.

      Note that the ratio of dimensions is only suitable if the full image has been extracted!

      Parameters:
      imp -
      server -
      Returns:

    • convertToPathObject

      @Deprecated public static PathObject convertToPathObject(ImagePlus imp, ImageServer<?> server, Roi roi, double downsampleFactor, Function<ROI,PathObject> creator, ImagePlane plane)
      Deprecated.
      use instead convertToPathObject(Roi, double, double, double, Function, ImagePlane)
      Create a PathObject for a specific ImageJ Roi. This method has been deprecated, since its signature was misleading (the server was not used).
      Parameters:
      imp -
      server -
      roi -
      downsampleFactor -
      creator -
      plane -
      Returns:

    • convertToPathObject

      public static PathObject convertToPathObject(Roi roi, double xOrigin, double yOrigin, double downsampleFactor, Function<ROI,PathObject> creator, ImagePlane plane)
      Create a PathObject for a specific ImageJ Roi.
      Parameters:
      roi - the ImageJ ROI
      xOrigin - the x-origin to translate the Roi; should be Calibration.xOrigin if available, or 0 otherwise
      yOrigin - the y-origin to translate the Roi; should be Calibration.yOrigin if available, or 0 otherwise
      downsampleFactor - the downsample factor used for rescaling (or 1.0 for no rescaling)
      creator - a function
      plane - the specific plane to use for the QuPath ROI; if null, the ImageJ Roi position properties will be used instead, where possible
      Returns:
      a PathObject or null if no object could be created (e.g. the ImageJ roi is null or incompatible)
      Since:
      v0.4.0
      See Also:

    • convertToPathObject

      public static PathObject convertToPathObject(Roi roi, double downsampleFactor, Function<ROI,PathObject> creator, ImagePlus imp)
      Create a PathObject for a specific ImageJ Roi, using an ImagePlus to help set properties.
      Parameters:
      roi - the ImageJ ROI
      downsampleFactor - the downsample factor used for rescaling (or 1.0 for no rescaling)
      creator - a function
      imp - the ImagePlus associated with this Roi; it is used to determine the xOrigin, yOrigin and image plane
      Returns:
      a PathObject or null if no object could be created (e.g. the ImageJ roi is null or incompatible)
      Since:
      v0.4.0
      See Also:

    • convertToAnnotation

      public static PathObject convertToAnnotation(Roi roi, double xOrigin, double yOrigin, double downsampleFactor, ImagePlane plane)
      Create an annotation object for a specific ImageJ Roi, using an ImagePlus to help set properties.
      Parameters:
      roi - the ImageJ ROI
      xOrigin - the x-origin to translate the Roi; should be Calibration.xOrigin if available, or 0 otherwise
      yOrigin - the y-origin to translate the Roi; should be Calibration.yOrigin if available, or 0 otherwise
      downsampleFactor - the downsample factor used for rescaling (or 1.0 for no rescaling)
      plane - the specific plane to use for the QuPath ROI; if null, the ImageJ Roi position properties will be used instead, where possible
      Returns:
      a PathObject or null if no object could be created (e.g. the ImageJ roi is null or incompatible)
      Since:
      v0.4.0
      See Also:

    • convertToDetection

      public static PathObject convertToDetection(Roi roi, double xOrigin, double yOrigin, double downsampleFactor, ImagePlane plane)
      Create a detection object for a specific ImageJ Roi, using an ImagePlus to help set properties.
      Parameters:
      roi - the ImageJ ROI
      xOrigin - the x-origin to translate the Roi; should be Calibration.xOrigin if available, or 0 otherwise
      yOrigin - the y-origin to translate the Roi; should be Calibration.yOrigin if available, or 0 otherwise
      downsampleFactor - the downsample factor used for rescaling (or 1.0 for no rescaling)
      plane - the specific plane to use for the QuPath ROI; if null, the ImageJ Roi position properties will be used instead, where possible
      Returns:
      a PathObject or null if no object could be created (e.g. the ImageJ roi is null or incompatible)
      Since:
      v0.4.0
      See Also:

    • convertToAnnotation

      public static PathObject convertToAnnotation(Roi roi, double downsampleFactor, ImagePlus imp)
      Create an annotation object for a specific ImageJ Roi.
      Parameters:
      roi - the ImageJ ROI
      downsampleFactor - the downsample factor used for rescaling (or 1.0 for no rescaling)
      imp - the ImagePlus associated with this Roi; it is used to determine the xOrigin, yOrigin and image plane
      Returns:
      a PathObject or null if no object could be created (e.g. the ImageJ roi is null or incompatible)
      Since:
      v0.4.0
      See Also:

    • convertToDetection

      public static PathObject convertToDetection(Roi roi, double downsampleFactor, ImagePlus imp)
      Create a detection object for a specific ImageJ Roi.
      Parameters:
      roi - the ImageJ ROI
      downsampleFactor - the downsample factor used for rescaling (or 1.0 for no rescaling)
      imp - the ImagePlus associated with this Roi; it is used to determine the xOrigin, yOrigin and image plane
      Returns:
      a PathObject or null if no object could be created (e.g. the ImageJ roi is null or incompatible)
      Since:
      v0.4.0
      See Also:

    • readImageJRois

      public static List<Roi> readImageJRois(File file)
      Read ImageJ Rois from a .roi or a RoiSet.zip file.
      Parameters:
      file -
      Returns:

    • containsImageJRois

      public static boolean containsImageJRois(File file)
      Check whether a file is likely to contain an ImageJ ROI, based upon its extension or .zip file contents.
      Parameters:
      file -
      Returns:
      true if the file seems to contain ImageJ ROIs, false otherwise

    • calibrateObject

      public static void calibrateObject(PathObject pathObject, Roi roi)
      Set the properties of a PathObject based upon an ImageJ Roi. This attempts to extract as much useful information as is relevant, including name, color and group.
      Parameters:
      pathObject -
      roi -

    • convertToAnnotation

      @Deprecated public static PathObject convertToAnnotation(ImagePlus imp, ImageServer<?> server, Roi roi, double downsampleFactor, ImagePlane plane)
      Deprecated.
      use instead convertToAnnotation(Roi, double, double, double, ImagePlane)
      Create an annotation object for a specific ImageJ Roi.
      Parameters:
      imp -
      server -
      roi -
      downsampleFactor -
      plane -
      Returns:

    • convertToDetection

      @Deprecated public static PathObject convertToDetection(ImagePlus imp, ImageServer<?> server, Roi roi, double downsampleFactor, ImagePlane plane)
      Deprecated.
      use instead convertToDetection(Roi, double, double, double, ImagePlane)
      Create an detection object for a specific ImageJ Roi.
      Parameters:
      imp -
      server -
      roi -
      downsampleFactor -
      plane -
      Returns:

    • convertLabelsToCells

      public static SortedMap<Number,PathObject> convertLabelsToCells(ImageProcessor ipNuclei, ImageProcessor ipCells, Calibration cal, double downsample, ImagePlane plane)
      Convert integer labeled images into cell objects.
      Parameters:
      ipNuclei - labels corresponding to cell nuclei; non-zero values here must be identical to the values in ipCells
      ipCells - labels corresponding to full cell areas
      cal - a Calibration object used to aid conversion between ImageJ and QuPath ROIs
      downsample - the downsample value for the ImageProcessors, used to aid conversion between ImageJ and QuPath ROIs
      plane - the ImagePlane defining where ROIs should be added
      Returns:
      a SortedMap containing integer labels from the original labeled images mapped to the corresponding cells that have been created

    • convertLabelsToCells

      public static SortedMap<Number,PathObject> convertLabelsToCells(ImageProcessor ipNuclei, ImageProcessor ipCells, double xOrigin, double yOrigin, double downsample, ImagePlane plane)
      Convert integer labeled images into cell objects.
      Parameters:
      ipNuclei - labels corresponding to cell nuclei; non-zero values here must be identical to the values in ipCells
      ipCells - labels corresponding to full cell areas
      xOrigin - the x pixel coordinate for the top left corner of the image, used to aid conversion between ImageJ and QuPath ROIs; equivalent to Calibration.xOrigin
      yOrigin - the y pixel coordinate for the top left corner of the image, used to aid conversion between ImageJ and QuPath ROIs; equivalent to Calibration.yOrigin
      downsample - the downsample value for the ImageProcessors, used to aid conversion between ImageJ and QuPath ROIs
      plane - the ImagePlane defining where ROIs should be added
      Returns:
      a SortedMap containing integer labels from the original labeled images mapped to the corresponding cells that have been created

    • quickShowImage

      public static void quickShowImage(String name, Roi roi, ImageProcessor... ips)
      Show an ImageProcessor (or array of similar ImageProcessors as a stack). This is really intended for use with debugging... it takes care of creating an ImagePlus with the specified title, reseting brightness/contrast suitably, setting a roi (if required) and showing the result.
      Parameters:
      name -
      roi -
      ips -

    • quickShowImage

      public static void quickShowImage(String name, ImageProcessor... ips)
      Show an ImageProcessor (or array of similar ImageProcessors as a stack). This is really intended for use with debugging... it takes care of creating an ImagePlus with the specified title, reseting brightness/contrast suitably and showing the result.
      Parameters:
      name -
      ips -

    • tryToParseMicrons

      public static double tryToParseMicrons(double value, String unit)
      Based on a value and its units, try to get something suitable in microns. (In other words, see if the units are 'microns' in some sense, and if not check if they are something else that can easily be converted).
      Parameters:
      value -
      unit -
      Returns:
      the parsed value in microns, or NaN if the unit couldn't be parsed

    • convertToUncalibratedImagePlus

      public static ImagePlus convertToUncalibratedImagePlus(String title, BufferedImage img)
      Convert a BufferedImage to an ImagePlus, without pixel size information or other calibration.
      Parameters:
      title -
      img -
      Returns:

    • createImageStack

      public static ImageStack createImageStack(ImageProcessor... ips)
      Create an ImageStack containing the specified ImageProcessors.
      Parameters:
      ips - the ImageProcessors. Each must be the same width, height and type. If empty, an empty stack is returned.
      Returns:

    • convertToImageProcessor

      public static ImageProcessor convertToImageProcessor(BufferedImage img, int band)
      Extract pixels as an an ImageProcessor from a single band of a BufferedImage.
      Parameters:
      img -
      band -
      Returns:

    • convertToImagePlus

      public static PathImage<ImagePlus> convertToImagePlus(String title, ImageServer<BufferedImage> server, BufferedImage img, RegionRequest request) throws IOException
      Convert a BufferedImage into a PathImage<ImagePlus>.

      An ImageServer and a RegionRequest are required to appropriate calibration.

      Parameters:
      title - a name to use as the ImagePlus title.
      server - the ImageServer from which the image was requested
      img - the image to convert - if null this will be requested from server.
      request - the region to request, or that was requested to provide img
      Returns:
      Throws:
      IOException

    • convertToImagePlus

      public static PathImage<ImagePlus> convertToImagePlus(ImageServer<BufferedImage> server, RegionRequest request) throws IOException
      Read a region from an ImageServer<BufferedImage as a PathImage<ImagePlus>.

      The PathImage element wraps up handy metadata that can be used for translating ROIs.

      Parameters:
      server -
      request -
      Returns:
      Throws:
      IOException

    • createPathImage

      public static PathImage<ImagePlus> createPathImage(ImageServer<BufferedImage> server, ImagePlus imp, RegionRequest request) throws IOException
      Create a PathImage from an ImagePlus and region. If imp is null, it is read from the server.
      Parameters:
      server -
      imp -
      request -
      Returns:
      Throws:
      IOException

    • convertToIJRoi

      public static <T extends PathImage<ImagePlus>> Roi convertToIJRoi(ROI pathROI, T pathImage)
      Create an ImageJ Roi from a ROI, suitable for displaying on the ImagePlus of an PathImage<ImagePlus>.
      Parameters:
      pathROI -
      pathImage -
      Returns:

    • convertToIJRoi

      public static <T extends PathImage<ImagePlus>> Roi convertToIJRoi(ROI pathROI, Calibration cal, double downsampleFactor)
      Convert a QuPath ROI to an ImageJ Roi for an image with the specified calibration.
      Type Parameters:
      T -
      Parameters:
      pathROI -
      cal -
      downsampleFactor -
      Returns:
      See Also:

    • convertToROI

      public static ROI convertToROI(Roi roi, Calibration cal, double downsampleFactor, ImagePlane plane)
      Create a ROI from an ImageJ Roi, using the Calibration object of an ImagePlus.
      Parameters:
      roi - ImageJ Roi
      cal - calibration object, including original information
      downsampleFactor - the downsample factor of the original image
      plane - plane defining c, z and t indices
      Returns:

    • getImagePlane

      public static ImagePlane getImagePlane(Roi roi, ImagePlus imp)
      Get the ImagePlane of an ImageJ Roi, based upon its stored positions.
      Parameters:
      roi - ImageJ roi that may have c, z, t or position properties set.
      imp - associated image; if not null, this will be used to convert the Roi's 'position' property, if non-zero
      Returns:
      the ImagePlane that is the best approximation of this Roi's position.

    • convertToROI

      public static <T extends PathImage<? extends ImagePlus>> ROI convertToROI(Roi roi, T pathImage)
      Create a ROI from an ImageJ Roi.
      Parameters:
      roi -
      pathImage -
      Returns:

    • convertToPolygonROI

      public static PolygonROI convertToPolygonROI(PolygonRoi roi, Calibration cal, double downsampleFactor, ImagePlane plane)
      Convert an ImageJ PolygonRoi to a QuPath PolygonROI.
      Parameters:
      roi -
      cal -
      downsampleFactor -
      plane -
      Returns:

    • convertToIJRoi

      public static <T extends PathImage<ImagePlus>> Roi convertToIJRoi(ROI pathROI, double xOrigin, double yOrigin, double downsampleFactor)
      Convert a QuPath ROI to an ImageJ Roi.
      Type Parameters:
      T -
      Parameters:
      pathROI -
      xOrigin - x-origin indicating relationship of ImagePlus to the original image, as stored in ImageJ Calibration object
      yOrigin - y-origin indicating relationship of ImagePlus to the original image, as stored in ImageJ Calibration object
      downsampleFactor - downsample factor at which the ImagePlus was extracted from the full-resolution image
      Returns:

    • convertToROI

      public static ROI convertToROI(Roi roi, double xOrigin, double yOrigin, double downsampleFactor, ImagePlane plane)
      Create a ROI from an ImageJ Roi.
      Parameters:
      roi - ImageJ Roi
      xOrigin - x-origin, as stored in an ImageJ Calibration object
      yOrigin - y-origin, as stored in an ImageJ Calibration object
      downsampleFactor -
      plane - plane defining c, z and t indices
      Returns:

    • convertToOpticalDensitySum

      public static FloatProcessor convertToOpticalDensitySum(ColorProcessor cp, double maxRed, double maxGreen, double maxBlue)
      Calculate optical density values for the red, green and blue channels, then add these all together.
      Parameters:
      cp -
      maxRed -
      maxGreen -
      maxBlue -
      Returns:

    • colorDeconvolve

      public static FloatProcessor[] colorDeconvolve(ColorProcessor cp, ColorDeconvolutionStains stains)
      Apply color deconvolution, outputting 3 'stain' images in the same order as the stain vectors.
      Parameters:
      cp - input RGB color image
      stains - color deconvolution stain vectors
      Returns:
      array containing three FloatProcessors, representing the deconvolved stains