Package qupath.opencv.dnn

Class DnnTools

java.lang.Object
qupath.opencv.dnn.DnnTools
public class DnnTools extends Object
Tools for working with OpenCV's DNN module.
Since:
0.3.0
Author:
Pete Bankhead

  • Constructor Details

    • DnnTools

      public DnnTools()

  • Method Details

    • registerDnnModel

      @Deprecated public static <T extends DnnModel> void registerDnnModel(Class<T> subtype, String name)
      Deprecated.
      since v0.4.0; use DnnModels.registerDnnModel(Class, String) instead.
      Register a new DnnModel class for JSON serialization/deserialization.
      Type Parameters:
      T -
      Parameters:
      subtype -
      name -

    • builder

      public static OpenCVDnn.Builder builder(String modelPath)
      Initiative building and configuring an OpenCVDnn.

      Note that DnnModels.buildModel(DnnModelParams) should generally be used instead to create an arbitrary DnnModel, since it can potentially use different libraries or frameworks.

      Parameters:
      modelPath -
      Returns:
      See Also:

    • isCudaAvailable

      public static boolean isCudaAvailable()
      Query whether CUDA is reported as available by OpenCV. If it is, it will be used by default until setUseCuda(boolean) is used to turn if off.
      Returns:

    • setUseCuda

      public static void setUseCuda(boolean requestUseCuda)
      Request that CUDA is used. This will be ignored if isCudaAvailable() returns false, therefore the main purpose of this method is to disable the use of CUDA if it would otherwise be employed.
      Parameters:
      requestUseCuda -

    • useCuda

      public static boolean useCuda()
      Returns true if CUDA is available and requested. Classes that could potentially use CUDA should query this request before attempting to use it.
      Returns:
      true if CUDA should be used, false otherwise

    • getOutputLayerNames

      public static List<String> getOutputLayerNames(Net net)
      Get the names of all unconnected output layers.
      Parameters:
      net -
      Returns:

    • getOutputLayers

      public static Map<String,DnnShape> getOutputLayers(Net net, DnnShape... inputShape)
      Get the names of all unconnected output layers.
      Parameters:
      net -
      inputShape -
      Returns:

    • parseLayers

      public static List<DnnTools.DNNLayer> parseLayers(Net net, int width, int height, int channels, int batchSize)
      Parse the layers for a Net, which allows inspection of names and sizes.
      Parameters:
      net - the Net to parse
      width - input width
      height - input height
      channels - input channels
      batchSize - input batch size
      Returns:

    • parseStrings

      public static List<String> parseStrings(StringVector vector)
      Extract Strings from a StringVector.
      Parameters:
      vector -
      Returns:

    • parseShape

      public static List<DnnShape> parseShape(MatShapeVector vector)
      Extract Mat dimensions from a MatShapeVector.
      Parameters:
      vector -
      Returns:

    • summarize

      public static String summarize(Net net, int width, int height, int nChannels) throws IOException
      Create a (multiline) summary String for a Net, given the specified image input dimensions.
      Parameters:
      net - the Net to summarize
      width - input width
      height - input height
      nChannels - input channel count
      Returns:
      Throws:
      IOException - if an error occurs when loading the model

    • readPatch

      public static Mat readPatch(ImageServer<BufferedImage> server, ROI roi, double downsample, int width, int height) throws IOException
      Read an image patch, optionally with a fixed size and using zero-padding if required. If the patch width and height are specified, these relate to the output (downsampled) image and are centered on the ROI centroid. Otherwise the ROI bounds are used.
      Parameters:
      server - the image server
      roi - the ROI for which the patch should be extracted
      downsample - the downsample value
      width - the patch width, or -1 if the ROI bounds should be used
      height - the patch height, or -1 if the ROI bounds should be used
      Returns:
      Throws:
      IOException
      See Also:

    • readPatch

      public static Mat readPatch(ImageServer<BufferedImage> server, ROI roi, double downsample, int width, int height, int borderPadding) throws IOException
      Read an image patch, optionally with a fixed size. If the patch width and height are specified, these relate to the output (downsampled) image and are centered on the ROI centroid. Otherwise the ROI bounds are used.
      Parameters:
      server - the image server
      roi - the ROI for which the patch should be extracted
      downsample - the downsample value
      width - the patch width, or -1 if the ROI bounds should be used
      height - the patch height, or -1 if the ROI bounds should be used
      borderPadding - the border padding for out-of-bounds requests, for use with OpenCV's copyMakeBorder
      Returns:
      Throws:
      IOException
      See Also:

    • classify

      public static boolean classify(ClassificationModel model, PathObject pathObject, ImageServer<BufferedImage> server, double downsample, IntFunction<PathClass> classifier, String predictionMeasurement) throws IOException
      Apply a classification model to an image patch to classify an object.
      Parameters:
      model - the model for prediction
      pathObject - the object to classify
      server - the image supplying the patch
      downsample - the requested downsample at which classification should be applied
      classifier - function to convert the classification label into a PathClass
      predictionMeasurement - optional measurement name for storing the prediction value (often treated as a probability) in the measurement list of the object.
      Returns:
      true if the classification of the object has changed, false otherwise
      Throws:
      IOException - if the patch cannot be read

    • classify

      public static boolean classify(ClassificationModel model, PathObject pathObject, ImageServer<BufferedImage> server, double downsample, int width, int height, IntFunction<PathClass> classifier, String predictionMeasurement) throws IOException, IllegalArgumentException
      Apply a classification model to an image patch to classify an object. If a patch width and height both > 0, the patch is cropped around the ROI centroid and padded if necessary. If a patch width and height both < 0, the bounding box of hte ROI is used directly and the model is assumed able to resize if needed. If the patch width and height are anything else, an IllegalArgumentException is thrown.
      Parameters:
      model - the model for prediction
      pathObject - the object to classify
      server - the image supplying the patch
      downsample - the requested downsample at which classification should be applied
      width - the fixed input size
      height - the fixed input size
      classifier - function to convert the classification label into a PathClass
      predictionMeasurement - optional measurement name for storing the prediction value (often treated as a probability) in the measurement list of the object.
      Returns:
      true if the classification of the object has changed, false otherwise
      Throws:
      IOException - if the patch cannot be read
      IllegalArgumentException - if the patch width or height are invalid

    • classify

      public static boolean classify(ClassificationModel model, PathObject pathObject, Mat input, IntFunction<PathClass> classifier, String predictionMeasurement)
      Apply a classification model to an existing image patch to classify an object.
      Parameters:
      model - the model for prediction
      pathObject - the object to classify
      input - image patch
      classifier - function to convert the classification label into a PathClass
      predictionMeasurement - optional measurement name for storing the prediction value (often treated as a probability) in the measurement list of the object.
      Returns:
      true if the classification of the object has changed, false otherwise

    • segment

      public static Mat segment(SegmentationModel model, ImageServer<BufferedImage> server, RegionRequest request) throws IOException
      Apply a segmentation model to an image region.
      Parameters:
      model - the segmentation model
      server - the image
      request - the region
      Returns:
      a Mat containing the segmentation results
      Throws:
      IOException - if the input image could not be read

    • segment

      public static Mat segment(SegmentationModel model, Mat input, Mat output)
      Apply a segmentation model to an image region.
      Parameters:
      model - the segmentation model
      input - the input image
      output - the output image
      Returns:
      a Mat containing the segmentation results (the same as output, if provided)

    • detect

      public static List<PathObject> detect(DetectionModel model, ImageServer<BufferedImage> server, RegionRequest request, IntFunction<PathClass> classifier, Function<ROI,PathObject> creator) throws IOException
      Apply a detection model to generate rectangles surrounding distinct structures.
      Parameters:
      model - the detection model
      server - the image
      request - the region within which detection should be applied
      classifier - function to convert the classification label into a PathClass
      creator - function to create an object (e.g. detection, annotation) from a ROI
      Returns:
      a list of created objects
      Throws:
      IOException - if the image could not be read

    • detect

      public static List<PathObject> detect(DetectionModel model, Mat mat, RegionRequest request, IntFunction<PathClass> classifier, Function<ROI,PathObject> creator)
      Apply a detection model to generate rectangles surrounding distinct structures.
      Parameters:
      model - the detection model
      mat - the image
      request - the region corresponding to the Mat; if provided, this is used to scale and translate detected regions
      classifier - function to convert the classification label into a PathClass
      creator - function to create an object (e.g. detection, annotation) from a ROI
      Returns:
      a list of created objects

    • blobFromImages

      public static Mat blobFromImages(Mat... mats)
      Create an OpenCV blob from one or more mats.
      Parameters:
      mats -
      Returns:

    • blobFromImage

      public static Mat blobFromImage(Mat mat)
      Create an OpenCV blob from a single mat.
      Parameters:
      mat -
      Returns:

    • blobFromImages

      public static Mat blobFromImages(Mat mat, double scaleFactor, Size size, Scalar mean, boolean swapRB, boolean crop)
      Create an OpenCV blob from a Mat with optional scaling, resizing and cropping.
      Parameters:
      mat - input image
      scaleFactor - scale factor
      size - input width and height
      mean - mean values for subtraction
      swapRB - swap red and blue of the mean values
      crop - center crop after resizing if needed
      Returns:
      a blob with axis order NCHW

    • blobFromImages

      public static Mat blobFromImages(Collection<Mat> mats, double scaleFactor, Size size, Scalar mean, boolean swapRB, boolean crop)
      Create an OpenCV blob from a batch of Mats with optional scaling, resizing and cropping.
      Parameters:
      mats - input images
      scaleFactor - scale factor
      size - input width and height
      mean - mean values for subtraction
      swapRB - swap red and blue of the mean values
      crop - center crop after resizing if needed
      Returns:
      a blob with axis order NCHW

    • imagesFromBlob

      public static List<Mat> imagesFromBlob(Mat blob)
      Extract images from an OpenCV blob.
      Parameters:
      blob -
      Returns:
      a list of of images, with length depending upon batch size