fetch_images | R Documentation |
Experiment level image meta data can be listed by passing experiment
representing objects (Experiment
or ExperimentIdentifier
) to
list_image_metadata()
and data set level image meta data can be retrieved
by passing data set identifying objects which can be associated with image
data sets (data set id and data set reference objects). Images themselves
can be retrieved using fetch_images()
. As with meta data listing, this
function can be dispatched on objects referencing or identifying data sets
associated with image data.
fetch_images(token, x, ...) ## S3 method for class 'DatasetIdentifier' fetch_images(token, x, channels, well_positions = NULL, image_size = NULL, thumbnails = FALSE, ...) ## S3 method for class 'DatasetReference' fetch_images(token, x, channels, well_positions = NULL, image_size = NULL, thumbnails = FALSE, ...) ## S3 method for class 'ImageDatasetReference' fetch_images(token, x, channels, well_positions = NULL, image_size = NULL, thumbnails = FALSE, ...) ## S3 method for class 'MicroscopyImageReference' fetch_images(token, x, well_positions = NULL, image_size = NULL, thumbnails = FALSE, ...) ## S3 method for class 'PlateImageReference' fetch_images(token, x, image_size = NULL, force_png = FALSE, format = NULL, thumbnails = FALSE, ...) list_image_metadata(token, x, ...) ## S3 method for class 'ExperimentIdentifier' list_image_metadata(token, x, ...) ## S3 method for class 'Experiment' list_image_metadata(token, x, ...) ## S3 method for class 'DatasetIdentifier' list_image_metadata(token, x, type = c("metadata", "format"), ...) ## S3 method for class 'DatasetReference' list_image_metadata(token, x, type = c("metadata", "format"), ...) ## S3 method for class 'ImageDatasetReference' list_image_metadata(token, x, type = c("metadata", "format"), ...) ## S3 method for class 'MicroscopyImageReference' list_image_metadata(token, x, type = c("metadata", "format"), ...) ## S3 method for class 'PlateImageReference' list_image_metadata(token, x, type = c("metadata", "format"), ...)
token |
Login token as created by |
x |
Object to limit the number of returned images |
... |
Generic compatibility. Extra arguments will be passed to
|
channels |
A character vector of imaging channels |
well_positions |
A (list of) |
image_size |
Either a single |
thumbnails |
Logical switch; if TRUE, thumbnail images are retrieved
in which case the arguments |
force_png |
Logical switch for making sure the returned image is a png. If NULL or FALSE, the image is returned in the format it is stored. |
format |
If not NULL, a single |
type |
Switch to specify the type of meta data objects to be returned. |
Data set level image meta data can be listed by passing objects, which
implement the IDatasetIdentifier
interface and are connected to image
data sets (this rules out feature data set references and leaves
DatasetIdentifier
, DatasetReference
, ImageDatasetReference
,
MicroscopyImageReference
and PlateImageReference
objects). Two
different types of meta data objects are returned, depending on the type
argument: if it is set to metadata
(default), objects of type
ImageDatasetMetadata
and if it is set to format
, objects of type
DatasetImageRepresentationFormats
are returned. For experiment-level
image meta data, ExperimentImageMetadata
objects are returned.
Dispatch of fetch_images()
is available for the same object types as data
set-level image meta data listing: DatasetIdentifier
, DatasetReference
,
ImageDatasetReference
, MicroscopyImageReference
and
PlateImageReference
. The highest level of control over which images are
retrieved is achieved with PlateImageReference
objects, which specify an
image data set, a well, a tile and a channel. The returned image format can
be modified by either passing an ImageRepresentationFormat
object as the
format
argument, by passing a single/list of format selection criterion
objects, which will be used to filter the available image representation
format objects or by specifying one or both of the image_size
(expects an
ImageSize
object) and force_png
(logical switch) arguments.
MicroscopyImageReference
objects contain channel information (as well as
tile information, which is not taken into account though). Therefore a
(list of) WellPosition
object(s) has/have to be specified, for which then
all tiles are fetched for the given imaging channel. If the passed list of
MicroscopyImageReference
objects contain instances that only differ in
tile number, redundancies are filtered out. An API call is necessary for
each non-redundant object.
Finally, DatasetIdentifier
, DatasetReference
and ImageDatasetReference
objects are all handled identically. For each of the specified data sets,
an imaging channel has to be provided and whenever the data set is
associated with an entire plate, a (list of) WellPosition
object(s) as
well. If the data set is associated with a single well, the
well_positions
can be left at its default value (NULL). If several data
sets are passed, an API call is necessary per data set. Possible
redundancies are not filtered.
Images are retrieved as Base64 encoded strings, which are converted to
binary using base64enc::base64decode()
and subsequently read by
magick::image_read()
. Attached to the images is the information, based
on which they were retrieved, including data set object, well positions
(where applicable) and channel (where applicable). This results in a list
with length corresponding to the number of API calls that were necessary.
For list_image_metadata()
, either a json_class
(single
object) or a json_vec
(multiple objects), is returned. For the specific
sub-class, refer to the Details section. Image data retrieved with
fetch_images()
is read by magick::image_read()
and returned as
(possibly nested) list
of magick-image
objects.
For dispatch on PlateImageReference
objects, currently the only options
controlling the returned images are an argument for image size and a flag
for forcing the returned format to png. OpenBIS also supports
pre-defined image transformations to be applied to the images before they
are sent to the requesting party. These transformations can be requested
by a code (options are listed in ImageRepresentationFormat
objects or
in ImageChannel
objects attached to ImageDatasetMetadata
objects).
However, as no such transformations appear to be defined, this is
currently not implemented.
When filtering ImageRepresentationFormat
objects associated with a data
set, only SizeCriterion
objects can be used. The remaining criteria
(ColorDepthCriterion
, FileTypeCriterion
and OriginalCriterion
) are
currently disabled as they extend the abstract class
AbstractFormatSelectionCriterion
, which causes an issue with JSON
deserialization.
Other resource listing/downloading functions: list_download_urls
,
list_features
, list_files
tok <- login_openbis() # search for a sample object corresponding to plate KB2-03-1I samp <- search_openbis(tok, search_criteria( attribute_clause("code", "/INFECTX_PUBLISHED/KB2-03-1I") ), target_object = "sample") # for the plate sample object, list raw image data set references ds_ref <- list_references(tok, samp) # the returned image dataset reference can be used to list image meta data img_meta <- list_image_metadata(tok, ds_ref) channels <- img_meta[["channelCodes"]] imgs <- fetch_images(tok, ds_ref, channels = channels[[1L]], well_positions = well_pos(1, 1), image_size = json_class(width = 300, height = 300, class = "ImageSize")) # this yields 9 images, one per tile length(imgs[[1L]]) == img_meta[["numberOfTiles"]] # and each image is scaled to fit within 300 x 300 pixels magick::image_info(imgs[[1L]][[1L]]) # if not the entire well is of interest, but only certain tiles img_ref <- list_references(tok, ds_ref, wells = well_pos(1, 1), channels = channels[[1L]]) # this yields 9 objects, one reference per tile length(img_ref) # select a tile, for example the center one img <- fetch_images(tok, img_ref[[5L]], image_size = json_class(width = 300, height = 300, class = "ImageSize")) identical(as.raster(img[[1L]]), as.raster(imgs[[1L]][[5L]])) logout_openbis(tok)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.