Package qupath.lib.io
Class PathIO
java.lang.Object
qupath.lib.io.PathIO
Primary class for loading/saving
ImageData objects.- Author:
- Pete Bankhead
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic enumOptions to customize the export of PathObjects as GeoJSON. -
Method Summary
Modifier and TypeMethodDescriptionstatic final ObjectInputStreamcreateObjectInputStream(InputStream stream) Create a newObjectInputStream, setting the defaultObjectInputFilterfor core QuPath-related and Java classes only.static voidexportObjectsAsGeoJSON(File file, Collection<? extends PathObject> pathObjects, PathIO.GeoJsonExportOptions... options) Export a collection of objects as a GeoJSON "FeatureCollection" to a file.static voidexportObjectsAsGeoJSON(OutputStream stream, Collection<? extends PathObject> pathObjects, PathIO.GeoJsonExportOptions... options) Export a collection of objects as a GeoJSON "FeatureCollection" to an output stream.static voidexportObjectsAsGeoJSON(Path path, Collection<? extends PathObject> pathObjects, PathIO.GeoJsonExportOptions... options) Export a collection of objects as a GeoJSON "FeatureCollection" to a file specified by its path.static <T> ImageServerBuilder.ServerBuilder<T>extractServerBuilder(Path file) Extract aImageServerBuilder.ServerBuilderfrom a serialized .qpdata file.static intGet the current preferred data file version.Deprecated.getObjectFileExtensions(boolean includeCompressed) Get a list of known file extensions that may contain objects, optionally including compressed files.static intGet the requested version for .qpdata files.static PathObjectHierarchyreadHierarchy(File file) Read a hierarchy from a .qpdata file.static PathObjectHierarchyreadHierarchy(InputStream fileIn) Read aPathObjectHierarchyfrom a saved data file (omitting all other contents).static PathObjectHierarchyreadHierarchy(Path path) Read a hierarchy from a .qpdata file.static <T> ImageData<T>readImageData(File file, ImageData<T> imageData, ImageServer<T> server, Class<T> cls) Read ImageData from a File into an existing ImageData object, or create a new one if required.static <T> ImageData<T>readImageData(InputStream stream, ImageData<T> imageData, ImageServer<T> server, Class<T> cls) Read ImageData from an InputStream into an existing ImageData object, or creating a new one if required.static <T> ImageData<T>readImageData(Path path, ImageData<T> imageData, ImageServer<T> server, Class<T> cls) ReadImageDatafrom a File into an existing ImageData object, or create a new one if required.static List<PathObject>readObjects(File file) Read a list ofPathObjectfrom a file.static List<PathObject>readObjects(Path path) Read a list ofPathObjectfrom a file.static List<PathObject>readObjectsFromGeoJSON(InputStream stream) Read a list ofPathObjectfrom an input stream.static StringreadSerializedServerPath(File file) Deprecated.This was useful in QuPath v0.1.2 and earlier, since all information to construct a server was stored within its path.static voidsetRequestedDataFileVersion(int version) Set the requested version for .qpdata files.unzippedExtensions(Path path, String... zipExtensions) Get the extension of a file, or of all entries within a zip file.static voidwriteImageData(File file, ImageData<?> imageData) Write (binary) file containingImageDatafor later use.static voidwriteImageData(OutputStream stream, ImageData<?> imageData) Serialize an ImageData object to an output stream.static voidwriteImageData(Path path, ImageData<?> imageData) Write (binary) file containingImageDatafor later use.
-
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
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
ImageServerpaths to be a JSON representation rather than a single path/URL - 4 Added support for UUID to be stored in each
PathObject(introducted QuPath v0.4.0)
- Parameters:
version- integer representation of the requested version- Throws:
IllegalArgumentException- if the requested version is less than 2 or greater thangetCurrentDataFileVersion()- 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:
IOExceptionFileNotFoundExceptionClassNotFoundException- See Also:
-
extractServerBuilder
public static <T> ImageServerBuilder.ServerBuilder<T> extractServerBuilder(Path file) throws IOException Extract aImageServerBuilder.ServerBuilderfrom a serialized .qpdata file.- Parameters:
file-- Returns:
- Throws:
IOException- if there is an error creating aImageServerBuilder.ServerBuilder, or the file is not a valid QuPath data file.- Since:
- 0.3
-
createObjectInputStream
public static final ObjectInputStream createObjectInputStream(InputStream stream) throws IOException Create a newObjectInputStream, setting the defaultObjectInputFilterfor core QuPath-related and Java classes only.- Parameters:
stream-- Returns:
- Throws:
IOException
-
readImageData
public static <T> ImageData<T> readImageData(InputStream stream, ImageData<T> imageData, ImageServer<T> server, Class<T> cls) throws IOException Read ImageData from an InputStream into an existing ImageData object, or creating a new one if required.- Parameters:
stream-imageData-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-- Returns:
- Throws:
IOException
-
readImageData
public static <T> ImageData<T> readImageData(File file, ImageData<T> imageData, ImageServer<T> server, Class<T> cls) throws IOException Read ImageData from a File into an existing ImageData object, or create a new one if required.- Type Parameters:
T-- Parameters:
file-imageData-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-- Returns:
- Throws:
IOException
-
readImageData
public static <T> ImageData<T> readImageData(Path path, ImageData<T> imageData, ImageServer<T> server, Class<T> cls) throws IOException ReadImageDatafrom a File into an existing ImageData object, or create a new one if required.- Type Parameters:
T-- Parameters:
path-imageData-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-- Returns:
- Throws:
IOException
-
writeImageData
public static void writeImageData(Path path, ImageData<?> imageData) throws FileNotFoundException, IOException Write (binary) file containingImageDatafor later use.- Parameters:
path-imageData-- Throws:
FileNotFoundExceptionIOException
-
writeImageData
public static void writeImageData(File file, ImageData<?> imageData) throws FileNotFoundException, IOException Write (binary) file containingImageDatafor later use.- Parameters:
file-imageData-- Throws:
FileNotFoundExceptionIOException
-
writeImageData
Serialize an ImageData object to an output stream.- Parameters:
stream-imageData-- Throws:
IOException
-
readHierarchy
public static PathObjectHierarchy readHierarchy(File file) throws FileNotFoundException, IOException Read a hierarchy from a .qpdata file.- Parameters:
file-- Returns:
- Throws:
IOExceptionFileNotFoundException
-
readHierarchy
public static PathObjectHierarchy readHierarchy(Path path) throws FileNotFoundException, IOException Read a hierarchy from a .qpdata file.- Parameters:
path-- Returns:
- Throws:
IOExceptionFileNotFoundException
-
readHierarchy
Read aPathObjectHierarchyfrom a saved data file (omitting all other contents).- Parameters:
fileIn-- Returns:
- Throws:
IOException
-
readObjects
Read a list ofPathObjectfrom a file. In generalreadObjects(Path)to be preferred for its more modern syntax. This exists for consistency with other QuPath methods that accept aFileobject as input.- Parameters:
file-- Returns:
- Throws:
IOException- See Also:
-
readObjects
Read a list ofPathObjectfrom 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
- Parameters:
path-- Returns:
- Throws:
IOException- See Also:
-
readObjectsFromGeoJSON
public static List<PathObject> readObjectsFromGeoJSON(InputStream stream) throws IOException, JsonSyntaxException, JsonParseException Read a list ofPathObjectfrom 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
- Parameters:
stream- the input stream containing JSON data to read- Returns:
- a list containing any PathObjects that could be parsed from the stream
- Throws:
IOExceptionJsonSyntaxExceptionJsonParseException
-
getObjectFileExtensions
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.usegetObjectFileExtensions(boolean)insteadGet 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
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 filezipExtensions- 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, useunzippedExtensions(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
-
getObjectFileExtensions(boolean)instead