Package qupath.lib.io

Class PathIO

java.lang.Object
qupath.lib.io.PathIO
public class PathIO extends Object
Primary class for loading/saving ImageData objects.

  • Method Details

    • getRequestedDataFileVersion

      public static int getRequestedDataFileVersion()
      Get the requested version for .qpdata files.
      Returns:
      See Also:

    • getCurrentDataFileVersion

      public static int getCurrentDataFileVersion()
      Get the current preferred data file version.
      Returns:
      See Also:

    • setRequestedDataFileVersion

      public static void setRequestedDataFileVersion(int version) throws IllegalArgumentException
      Set the requested version for .qpdata files.
      • 1.0 Initial version stored in very early .qpdata files (no longer supported)
      • 2 Switched versions to use integers, added Locale information (used in QuPath v0.1.2)
      • 3 Switched ImageServer paths to be a JSON representation rather than a single path/URL
      • 4 Added support for UUID to be stored in each PathObject (introduced QuPath v0.4.0)
      Parameters:
      version - integer representation of the requested version
      Throws:
      IllegalArgumentException - if the requested version is less than 2 or greater than getCurrentDataFileVersion()
      Since:
      v0.4.0
      See Also:

    • readSerializedServerPath

      @Deprecated public static String readSerializedServerPath(File file) throws FileNotFoundException, IOException, ClassNotFoundException
      Deprecated.
      This was useful in QuPath v0.1.2 and earlier, since all information to construct a server was stored within its path. In v0.2 and later, the server path is in general not sufficient to construct a server, and this method lingers only for backwards compatibility. It will be removed in a later version.
      Read the server path from a serialized file, if present. This is assumed to be the first line within the file.
      Parameters:
      file -
      Returns:
      The server path that is stored within the file, or null if no path could be found.
      Throws:
      IOException
      FileNotFoundException
      ClassNotFoundException
      See Also:

    • extractServerBuilder

      public static <T> ImageServerBuilder.ServerBuilder<T> extractServerBuilder(Path file) throws IOException
      Extract a ImageServerBuilder.ServerBuilder from a serialized .qpdata file.
      Parameters:
      file -
      Returns:
      Throws:
      IOException - if there is an error creating a ImageServerBuilder.ServerBuilder, or the file is not a valid QuPath data file.
      Since:
      0.3

    • createObjectInputStream

      public static ObjectInputStream createObjectInputStream(InputStream stream) throws IOException
      Create a new ObjectInputStream, setting the default ObjectInputFilter for core QuPath-related and Java classes only.
      Parameters:
      stream -
      Returns:
      Throws:
      IOException

    • readImageData

      @Deprecated public static <T> ImageData<T> readImageData(File file, ImageData<T> imageData, ImageServer<T> server, Class<T> cls) throws IOException
      Deprecated.
      since v0.6.0
      Legacy method to read an ImageData from a file.

      This previously tried to reuse an existing ImageData if it referred to the same ImageServer, but in practice it usually returned a new ImageData object instead. Therefore this method is deprecated, and readImageData(Path, ImageServer) should be used instead.

      Parameters:
      file - the .qpdata file
      imageData - optional existing ImageData, to update if possible
      server - an ImageServer to use rather than any that might be stored within the serialized data. Should be null to use the serialized path to build a new server. The main purpose of this is to make it possible to open ImageData where the original image location has been moved, so the stored path is no longer accurate.
      cls - the generic class for the ImageServer
      Returns:
      Throws:
      IOException

    • readImageData

      @Deprecated public static <T> ImageData<T> readImageData(Path path, ImageData<T> imageData, ImageServer<T> server, Class<T> cls) throws IOException
      Deprecated.
      since v0.6.0
      Legacy method to read an ImageData from a file.

      This previously tried to reuse an existing ImageData if it referred to the same ImageServer, but in practice it usually returned a new ImageData object instead. Therefore this method is deprecated, and readImageData(Path, ImageServer) should be used instead.

      Parameters:
      path - the .qpdata file
      imageData - optional existing ImageData, to update if possible
      server - an ImageServer to use rather than any that might be stored within the serialized data. Should be null to use the serialized path to build a new server. The main purpose of this is to make it possible to open ImageData where the original image location has been moved, so the stored path is no longer accurate.
      cls - the generic class for the ImageServer
      Returns:
      Throws:
      IOException

    • readImageData

      @Deprecated public static <T> ImageData<T> readImageData(InputStream stream, ImageData<T> imageData, ImageServer<T> server, Class<T> cls) throws IOException
      Deprecated.
      since v0.6.0
      Legacy method to read an ImageData from a stream.

      This previously tried to reuse an existing ImageData if it referred to the same ImageServer, but in practice it usually returned a new ImageData object instead. Therefore this method is deprecated, and readImageData(Path, ImageServer) should be used instead.

      Parameters:
      stream - data stream containing the serialized ImageData
      imageData - optional existing ImageData, to update if possible
      server - an ImageServer to use rather than any that might be stored within the serialized data. Should be null to use the serialized path to build a new server. The main purpose of this is to make it possible to open ImageData where the original image location has been moved, so the stored path is no longer accurate.
      cls - the generic class for the ImageServer
      Returns:
      Throws:
      IOException

    • readImageData

      public static <T> ImageData<T> readImageData(Path path, ImageServerBuilder.ServerBuilder<T> serverBuilder) throws IOException
      Read an ImageData, optionally providing a serverBuilder for lazy image loading.
      Parameters:
      path - the .qpdata file to read
      serverBuilder - the server builder to use, or null to use the one stored in the file
      Returns:
      Throws:
      IOException

    • readImageData

      public static <T> ImageData<T> readImageData(InputStream stream, ImageServerBuilder.ServerBuilder<T> serverBuilder) throws IOException
      Read an ImageData, optionally providing a serverBuilder for lazy image loading.
      Parameters:
      stream - the .qpdata file to read
      serverBuilder - the server builder to use, or null to use the one stored in the file
      Returns:
      Throws:
      IOException

    • readImageData

      public static <T> ImageData<T> readImageData(File file) throws IOException
      Read and initialize an ImageData from a data file.
      Parameters:
      file - the .qpdata file to read
      Returns:
      Throws:
      IOException

    • readImageData

      public static <T> ImageData<T> readImageData(Path path) throws IOException
      Read and initialize an ImageData from a data file.
      Parameters:
      path - the .qpdata file to read
      Returns:
      Throws:
      IOException

    • readImageData

      public static <T> ImageData<T> readImageData(File file, ImageServer<T> server) throws IOException
      Read and initialize an ImageData from a data file.
      Type Parameters:
      T - generic parameter for the ImageServer, usually BufferedImage
      Parameters:
      file - the .qpdata file to read
      server - an ImageServer to use rather than any that might be stored within the serialized data. Should be null to use the serialized path to build a new server. The main purpose of this is to make it possible to open ImageData where the original image location has been moved, so the stored path is no longer accurate.
      Returns:
      Throws:
      IOException

    • readImageData

      public static <T> ImageData<T> readImageData(Path path, ImageServer<T> server) throws IOException
      Read and initialize an ImageData from a data file.
      Type Parameters:
      T - generic parameter for the ImageServer, usually BufferedImage
      Parameters:
      path - path to data file
      server - an ImageServer to use rather than any that might be stored within the serialized data. Should be null to use the serialized path to build a new server. The main purpose of this is to make it possible to open ImageData where the original image location has been moved, so the stored path is no longer accurate.
      Returns:
      Throws:
      IOException

    • writeImageData

      public static void writeImageData(Path path, ImageData<?> imageData) throws FileNotFoundException, IOException
      Write (binary) file containing ImageData for later use.
      Parameters:
      path -
      imageData -
      Throws:
      FileNotFoundException
      IOException

    • writeImageData

      public static void writeImageData(File file, ImageData<?> imageData) throws FileNotFoundException, IOException
      Write (binary) file containing ImageData for later use.
      Parameters:
      file -
      imageData -
      Throws:
      FileNotFoundException
      IOException

    • writeImageData

      public static void writeImageData(OutputStream stream, ImageData<?> imageData) throws IOException
      Serialize an ImageData object to an output stream.
      Parameters:
      stream -
      imageData -
      Throws:
      IOException

    • readHierarchy

      public static PathObjectHierarchy readHierarchy(File file) throws IOException
      Read a hierarchy from a .qpdata file.
      Parameters:
      file -
      Returns:
      Throws:
      IOException
      FileNotFoundException

    • readHierarchy

      public static PathObjectHierarchy readHierarchy(Path path) throws IOException
      Read a hierarchy from a .qpdata file.
      Parameters:
      path -
      Returns:
      Throws:
      IOException

    • readHierarchy

      public static PathObjectHierarchy readHierarchy(InputStream fileIn) throws IOException
      Read a PathObjectHierarchy from a saved data file (omitting all other contents).
      Parameters:
      fileIn -
      Returns:
      Throws:
      IOException

    • readObjects

      public static List<PathObject> readObjects(File file) throws IOException
      Read a list of PathObject from a file. In general readObjects(Path) to be preferred for its more modern syntax. This exists for consistency with other QuPath methods that accept a File object as input.
      Parameters:
      file -
      Returns:
      Throws:
      IOException
      See Also:

    • readObjects

      public static List<PathObject> readObjects(Path path) throws IOException
      Read a list of PathObject from a file.

      Currently, objects can be read from three main types of file:

      • GeoJSON, with extension .geojson or .json
      • QuPath data file, with extension .qpdata
      • A zip file containing one or more entries containing GeoJSON or QuPath serialized data
      Note that this is subject to change, with support for other files possibly being added in the future.
      Parameters:
      path -
      Returns:
      Throws:
      IOException
      See Also:

    • readObjectsFromGeoJSON

      public static List<PathObject> readObjectsFromGeoJSON(InputStream stream) throws IOException, JsonSyntaxException, JsonParseException
      Read a list of PathObject from an input stream.

      This will attempt to handle different GeoJSON representations by first deserializing to a JSON element.

      If the element is a JSON object, its "type" property is checked and handled as follows

      • "Feature": a single PathObject will be read
      • "FeatureCollection": a list of PathObject will be read
      • a valid geometry type: a Geometry will be read, converted to a ROI and subsequently to an annotation
      • anything else: the element is skipped, since a PathObject cannot be read from it
      If the element is a JSON array, its individual elements are handled as above.
      Parameters:
      stream - the input stream containing JSON data to read
      Returns:
      a list containing any PathObjects that could be parsed from the stream
      Throws:
      IOException
      JsonSyntaxException
      JsonParseException

    • getObjectFileExtensions

      public static List<String> getObjectFileExtensions(boolean includeCompressed)
      Get a list of known file extensions that may contain objects, optionally including compressed files.
      Parameters:
      includeCompressed - if true, include extensions for any compressed files that might contain objects (e.g. .zip)
      Returns:
      file extensions for files from which objects can be read.
      Since:
      v0.4.0
      See Also:

    • getObjectFileExtensions

      @Deprecated public static List<String> getObjectFileExtensions()
      Deprecated.
      use getObjectFileExtensions(boolean) instead
      Get a list of known file extensions that may contain objects.
      Returns:
      file extensions for files from which objects can be read.
      See Also:

    • exportObjectsAsGeoJSON

      public static void exportObjectsAsGeoJSON(File file, Collection<? extends PathObject> pathObjects, PathIO.GeoJsonExportOptions... options) throws IOException
      Export a collection of objects as a GeoJSON "FeatureCollection" to a file.
      Parameters:
      file -
      pathObjects -
      options -
      Throws:
      IOException
      See Also:

    • exportObjectsAsGeoJSON

      public static void exportObjectsAsGeoJSON(Path path, Collection<? extends PathObject> pathObjects, PathIO.GeoJsonExportOptions... options) throws IOException
      Export a collection of objects as a GeoJSON "FeatureCollection" to a file specified by its path.
      Parameters:
      path -
      pathObjects -
      options -
      Throws:
      IOException

    • exportObjectsAsGeoJSON

      public static void exportObjectsAsGeoJSON(OutputStream stream, Collection<? extends PathObject> pathObjects, PathIO.GeoJsonExportOptions... options) throws IOException
      Export a collection of objects as a GeoJSON "FeatureCollection" to an output stream.
      Parameters:
      stream -
      pathObjects -
      options -
      Throws:
      IOException

    • unzippedExtensions

      public static Set<String> unzippedExtensions(Path path, String... zipExtensions) throws IOException
      Get the extension of a file, or of all entries within a zip file. This is useful to check the contents of a file before attempting to read any of it, for example to confirm if the file is likely to contain images or objects.

      Note that the identification of the zip file is based solely on the file extension, but the attempt to extracted zipped entries will fail if the file is not a valid zip file.

      Parameters:
      path - path representing a file or zip file
      zipExtensions - optional list of extensions to treat as representing zip files. If none are specified, the default is to use '.zip'. If jar files should be included, use unzippedExtensions(path, ".zip", ".jar").
      Returns:
      the file extensions for entries within a zip file, or the file extension of path itself if it is not identified as being a zip file. Note that all extensions are converted to lowercase.
      Throws:
      IOException
      Since:
      v0.4.0
      Implementation Note
      this returns original the extension for a non-zip file so that it may be used more easily within a stream.