slideio module
The entry points of the library: slideio::openSlide(), slideio::getDriverIDs() and the slideio::Slide and slideio::Scene classes. slideio::makeScene() builds a scene whose pixels the caller computes. Headers are included as <slideio/slideio/...>; linking slideio::slideio is enough.
slideio.hpp
-
namespace slideio
slideio: main Slideio namespace
Typedefs
-
using SlideOpenOptions = std::map<std::string, std::string>
Open options: driver-namespaced key -> value strings.
Functions
-
std::shared_ptr<Slide> openSlide(const std::string &path, const std::string &driver = "")
The function returns a smart pointer to an object of Slide class.
Function for opening a slide file.
- Parameters:
path – : path of the file/folder that contains the slide.
driver – : id of image driver, as returned by getDriverIDs(). An empty string or “AUTO” selects the driver by the content of the file. The function throws an exception if the id is unknown or if no driver accepts the file.
-
std::shared_ptr<Slide> openSlide(const std::string &path, const std::string &driver, const SlideOpenOptions &options)
Opens a slide as openSlide(path, driver) does, passing options to the driver.
Function for opening a slide file with open options.
- Parameters:
path – : path of the file/folder that contains the slide.
driver – : id of image driver, or an empty string or “AUTO” to detect it.
options – : every key is written
<driver-id>.<name>; the driver id is matched case-insensitively against getDriverIDs(), the name exactly. Keys addressed to a driver other than the one that opens the file are ignored. The function throws, before the file is opened, for a key without a driver prefix or with an unknown one, and the driver throws for a name or value it does not know. Boolean values are true/false/1/0. Known options:mrxs.crop_to_content(default true): the MRXS scene is the bounding box of the scanned area, with coordinates starting at its corner; false gives the full canvas.
-
std::vector<std::string> getDriverIDs()
Returns a list of available driver ids.
-
void setLogLevel(const std::string &level)
Sets the log level for the library.
-
std::string getVersion()
returns version of the library.
-
using SlideOpenOptions = std::map<std::string, std::string>
slide.hpp
Defines
-
SlidePtr
-
namespace slideio
slideio: main Slideio namespace
-
class Slide
- #include <slideio/slideio/slide.hpp>
Slide class is an interface for accessing the information on a medical slide.
Slide class is an interface for accessing the information on a medical Slide class represents a medical slide. A medical slide is normally a is represented by a single file or folder. A slide may contain multiple images represented by the Scene class. Additionally a slide may contain a number of auxiliary images like labels, macro, etc. Objects of the class can be obtained by calling of slideio::openSlide() global function.
Public Functions
-
virtual ~Slide()
-
std::string getFilePath() const
The method returns a string which represents file path of the slide.
-
std::shared_ptr<Scene> getScene(int index) const
The method returns a Scene object by the scene index.
-
std::shared_ptr<Scene> getSceneByName(const std::string &name) const
The method returns a Scene object by the scene name.
-
const std::string &getRawMetadata() const
The method returns a string containing serialized metadata of the slide.
Content of the string depends on image driver and may be plain text, xml or json formatted string. Default value is an empty string.
-
MetadataFormat getMetadataFormat() const
The method returns the format of the metadata returned by getRawMetadata.
-
const Metadata &getMetadata() const
returns metadata as a navigable tree. Built lazily on first call.
-
const std::list<std::string> &getAuxImageNames() const
The method returns list of names of auxiliary images contained in the slide.
Default: empty list.
-
virtual int getNumAuxImages() const
The method returns number of auxiliary images contained in the slide.
-
virtual std::shared_ptr<Scene> getAuxImage(const std::string &sceneName) const
Returns a Scene object that represents an auxiliary image with the supplied name.
- Parameters:
sceneName – : name of the auxiliary image. It must be contained in the list returned by getAuxImageNames method.
-
std::string toString() const
The method returns a human readable description of the slide.
The description contains the file path, the driver id, the metadata format, the number of scenes, the names of the auxiliary images and the beginning of the raw metadata. It is intended for logging and diagnostics; its layout is not part of the API.
-
void setDriverId(const std::string &driverId)
-
const std::string &getDriverId() const
The method returns the id of the image driver that opened the slide.
Private Functions
Constructor of the class.
- Parameters:
slide – : object of a CVSlide class created by a corresponding ImageDriver object.
Private Members
-
std::shared_ptr<CVSlide> m_slide
Friends
-
friend std::shared_ptr<Slide> openSlide(const std::string &path, const std::string &driver)
The function returns a smart pointer to an object of Slide class.
Function for opening a slide file.
- Parameters:
path – : path of the file/folder that contains the slide.
driver – : id of image driver, as returned by getDriverIDs(). An empty string or “AUTO” selects the driver by the content of the file. The function throws an exception if the id is unknown or if no driver accepts the file.
-
friend std::shared_ptr<Slide> openSlide(const std::string &path, const std::string &driver, const std::map<std::string, std::string> &options)
Opens a slide as openSlide(path, driver) does, passing options to the driver.
Function for opening a slide file with open options.
- Parameters:
path – : path of the file/folder that contains the slide.
driver – : id of image driver, or an empty string or “AUTO” to detect it.
options – : every key is written
<driver-id>.<name>; the driver id is matched case-insensitively against getDriverIDs(), the name exactly. Keys addressed to a driver other than the one that opens the file are ignored. The function throws, before the file is opened, for a key without a driver prefix or with an unknown one, and the driver throws for a name or value it does not know. Boolean values are true/false/1/0. Known options:mrxs.crop_to_content(default true): the MRXS scene is the bounding box of the scanned area, with coordinates starting at its corner; false gives the full canvas.
-
virtual ~Slide()
-
class Slide
scene.hpp
Defines
-
ScenePtr
-
namespace slideio
slideio: main Slideio namespace
-
class Scene
- #include <slideio/slideio/scene.hpp>
Scene class represents a raster image contained in a slide.
Scene class allows extracting information from image of a slide. It includes raster data as well as metadata. The object supports multichannel multi-dimensional rasters. The class provides methods for resampling of multi-dimensional rasters.
Thread safety: block reads of one Scene are always safe to call from several threads. Whether they overlap depends on the driver: a scene whose driver supports concurrent reads runs them in parallel, otherwise the library serialises them internally. Callers that relied on reads of one scene being mutually exclusive in order to protect their own state must take their own lock.
Lifetime is the caller’s responsibility: a Scene or the Slide it came from must not be destroyed while a read on it is still in flight. Keep the shared_ptr alive (or join the reader threads) until every read has returned. The library does not make a close wait for in-flight reads.
Public Functions
-
inline virtual ~Scene()
-
std::string getFilePath() const
returns path of the slide
-
std::string getName() const
returns scene name
-
std::tuple<int, int, int, int> getRect() const
returns image rectangle in pixels.
Rectangle is represented as std::tuple (x,y,width,height). Where:
x,y - image origins (pixel coordinates of the left top corner of the image in slide coordinates),
width - image width in pixels,
height - image height in pixels.
Note
Scene origins should be ignored for reading of image rasters.
-
int getNumChannels() const
returns number of raster channels of the image
-
int getNumZSlices() const
returns number of slices for 3D/4D images.
The method returns 1 for 2D images.
-
int getNumTFrames() const
returns number of time frames for 3D/4D images.
The method returns 1 for images without time frames.
-
Compression getCompression() const
returns compression of the raster data
-
slideio::DataType getChannelDataType(int channel) const
brief returns data type of a channel
- Parameters:
channel – : index of the channel. Should be in the range (0, numberOfChannels)
-
std::string getChannelName(int channel) const
returns channel name.
- Parameters:
channel – : index of the channel. Should be in the range (0, numberOfChannels)
-
std::tuple<double, double> getResolution() const
returns image resolution in x and y direction.
Resolution is returned as a std::tuple (resolutionXdirection, resolutionYdirection). Resolution is size of a pixel in meters.
-
double getZSliceResolution() const
returns thickness of a Z slice in meters for 3D images.
-
double getTFrameResolution() const
returns time between 2 time frames in seconds for images with time frames.
-
int getChannelSignificantBits(int channelIndex) const
native significant bits of a channel; 0 when unknown.
- Parameters:
channelIndex – : index of the channel, in the range (0, numberOfChannels)
-
bool hasPlaneTimestamps() const
true if every plane of the scene has a timestamp.
-
double getPlaneTimestamp(int tFrame, int channel, int zSlice) const
when one plane was acquired, in seconds from the scene’s acquisition origin.
The origin is the acquisition start recorded in the file – the instant getAcquisitionTime() reports – or the scene’s earliest plane where the file records none. Timestamps are never negative, but the earliest plane is 0 only where it is itself the origin: a recorded start may precede the first exposure. Differences between planes are always meaningful; an absolute time needs getAcquisitionTime() to be non-zero. Returns 0 if hasPlaneTimestamps() is false or an index is out of range.
-
int64_t getAcquisitionTime() const
acquisition start in seconds since 1970-01-01T00:00:00Z, 0 if unknown.
This is the origin getPlaneTimestamp() measures from, so the absolute time of a plane is getAcquisitionTime() + getPlaneTimestamp(tFrame, channel, zSlice).
-
double getMagnification() const
returns slide magnification extracted from the slide metadata.
-
int getBlockSize(const std::tuple<int, int> &blockSize, int refChannel, int numChannels, int numSlices, int numFrames) const
returns memory size in the bytes required for a raster block.
- Parameters:
blockSize – : a std::tuple<int,int> defining with and height of the image block;
refChannel – : index of the first channel to be included in the block;
numChannels – : number of channels in the block;
numSlices – : number of Z slices in the block. For plane images it shall be 1;
numFrames – : number of time frames in the block. For plane images it shall be 1;
-
void readBlock(const std::tuple<int, int, int, int> &blockRect, void *buffer, size_t bufferSize)
reads raster rectangle of a plane image to a memory buffer.
All channels have to be of the same type. The method will throw an error by attempt to put read several channels of different types in one block. The raster will be placed in the memory buffer. The raster is organized as a continuous 3-dimensional array.
where:DataType raster[numberOfRows][numberOfColumns][numberOfChannels];
DataType is a channel data type (i.e. uint8_t, uint16_t, …, float, double);
numberOfChannels: number of channels in the block;
numberOfRows: width of the block in pixels;
numberOfColumns: height of the block in pixels; The following code snippet can be used to compute a location of a channel i uint16_t channel of a pixel with coordinates x, y:
// convert buffer to the correct data type uint16_t* typedBuff = (uint16_t*) buffer; // compute value location uint32_t location = (numberOfChannels*numberOfColumns)*y + (numberOfChannels*x) + i; // extract value from the buffer uint16_t channelValue = typedBuffer[location];
- Parameters:
blockRect – : rectangle of the block to be read. The rectangle is represented by std::tuple(x,y,with,height). Here:
x, y: pixel coordinates of the top left corner of the block in image coordinates (pixel shifts of the left top corner of the block;
width: block width in pixels;
height: block height in pixels; from left top corner of the image).
buffer – : pointer to an allocated memory buffer for the raster block. Size of the block can be computed with the method getBlockSize;
bufferSize – : size of the memory buffer in bytes.
-
void readBlockChannels(const std::tuple<int, int, int, int> &blockRect, const std::vector<int> &channelIndices, void *buffer, size_t bufferSize)
reads raster rectangle plane image combined from selected channels to a memory buffer.
All channels have to be of the same type. The method will throw an error by attempt to put read several channels of different types in one block. The raster will be placed in the memory buffer. Memory layout of the buffer is described in the readBlock method.
- Parameters:
blockRect – : rectangle of the block to be read. The rectangle is represented by std::tuple(x,y,with,height). Here:
x, y: pixel coordinates of the top left corner of the block in image coordinates (pixel shifts of the left top corner of the block;
width: block width in pixels;
height: block height in pixels; from left top corner of the image).
channelIndices – : vector of indices of channels to be extracted;
buffer – : pointer to an allocated memory buffer for the raster block. Size of the block can be computed with the method getBlockSize;
bufferSize – : size of the memory buffer in bytes.
-
void readResampledBlock(const std::tuple<int, int, int, int> &blockRect, const std::tuple<int, int> &blockSize, void *buffer, size_t bufferSize)
reads raster rectangle plane image and resizes it to the size specified in the parameters.
All channels have to be of the same type. The method will throw an error by attempt to put read several channels of different types in one block. The raster will be placed in the memory buffer. Memory layout of the buffer is described in the readBlock method.
Note
the size should be large enough to fit resized block (i.e. with width equal std::get<0>(blockSize), and height equal std::get<1>(blockSize);
- Parameters:
blockRect – : rectangle of the block to be read. The rectangle is represented by std::tuple<x,y,with,height>. Here:
x, y: pixel coordinates of the top left corner of the block in image coordinates (pixel shifts of the left top corner of the block;
width: block width in pixels;
height: block height in pixels; from left top corner of the image).
blockSize – : size of the block after resizing. The size is set as a std::tuple<width,height>;
buffer – : pointer to an allocated memory buffer for the raster block. Size of the block can be computed with the method getBlockSize.
bufferSize – : size of the memory buffer in bytes.
-
void readResampledBlockChannels(const std::tuple<int, int, int, int> &blockRect, const std::tuple<int, int> &blockSize, const std::vector<int> &channelIndices, void *buffer, size_t bufferSize)
reads raster rectangle plane image combined from selected channels and resizes it to the size specified in the parameters.
All channels have to be of the same type. The method will throw an error by attempt to put read several channels of different types in one block. The raster will be placed in the memory buffer. Memory layout of the buffer is described in the readBlock method.
Note
the size should be large enough to fit resized block (i.e. with width equal std::get<0>(blockSize), and height equal std::get<1>(blockSize);
- Parameters:
blockRect – : rectangle of the block to be read. The rectangle is represented by std::tuple<x,y,with,height>. Here:
x, y: pixel coordinates of the top left corner of the block in image coordinates (pixel shifts of the left top corner of the block;
width: block width in pixels;
height: block height in pixels; from left top corner of the image).
blockSize – : size of the block after resizing. The size is set as a std::tuple<width,height>;
channelIndices – : vector of indices of channels to be extracted;
buffer – : pointer to an allocated memory buffer for the raster block. Size of the block can be computed with the method getBlockSize.
bufferSize – : size of the memory buffer in bytes.
-
void read4DBlock(const std::tuple<int, int, int, int> &blockRect, const std::tuple<int, int> &zSliceRange, const std::tuple<int, int> &timeFrameRange, void *buffer, size_t bufferSize)
reads multi-dimensional raster block to a memory buffer.
All channels have to be of the same type. The method will throw an error by attempt to put read several channels of different types in one block. The raster will be placed in the memory buffer. The raster is organized as a continuous multi-dimensional array.
where:DataType raster[numberOfTimeFramesToRead][numberOfzSlicesToRead][numberOfBlockRows][numberOfBlockColumns][numberOfBlockChannels];
DataType is a channel data type (i.e. uint8_t, uint16_t, …, float, double);
numberOfChannels: number of channels in the block;
numberOfRows: width of the block in pixels;
numberOfColumns: height of the block in pixels; The following code snippet can be used to compute a location of a channel i uint16_t channel of a pixel with coordinates x, y located in time frame tz and zSlice zs:
// convert buffer to the correct data type uint16_t* typedBuff = (uint16_t*) buffer; // compute row size uint32_t rowSize = numberOfBlockChannels*numberOfBlockColumns; // compute slice size uint32_t sliceSize = numberOfBlockRows*rowSize; // compute time frame size uint32_t tframeSize = numberOfzSlicesToRead*sliceSize; // compute value location uint32_t location = tf*tframeSize + zs*sliceSize + y*rowSize + (numberOfChannels*x) + i; // extract value from the buffer uint16_t channelValue = typedBuffer[location];
- Parameters:
blockRect – : rectangle of the block to be read. The rectangle is represented by std::tuple(x,y,with,height). Here:
x, y: pixel coordinates of the top left corner of the block in image coordinates (pixel shifts of the left top corner of the block;
width: block width in pixels;
height: block height in pixels; from left top corner of the image).
zSliceRange – : range of z-slices to be read. Defined as a std::tuple<indexOfFirstSliceToRead,indexAfterLastSliceToRead>
timeFrameRange – : range of time frames to be read. Defined as a std::tuple<indexOfFirstTimeFrameToRead,indexAfterLastTimeFrameToRead>;
buffer – : pointer to an allocated memory buffer for the raster block. Size of the block can be computed with the method getBlockSize;
bufferSize – : size of the memory buffer in bytes.
-
void read4DBlockChannels(const std::tuple<int, int, int, int> &blockRect, const std::vector<int> &channelIndices, const std::tuple<int, int> &zSliceRange, const std::tuple<int, int> &timeFrameRange, void *buffer, size_t bufferSize)
reads selected channels of multi-dimensional raster block to a memory buffer.
All channels have to be of the same type. The method will throw an error by attempt to put read several channels of different types in one block. The raster will be placed in the memory buffer. The raster is organized as a continuous multi-dimensional array. Memory layout is the same as in read4DBlock method.
- Parameters:
blockRect – : rectangle of the block to be read. The rectangle is represented by std::tuple(x,y,with,height). Here:
x, y: pixel coordinates of the top left corner of the block in image coordinates (pixel shifts of the left top corner of the block;
width: block width in pixels;
height: block height in pixels; from left top corner of the image).
channelIndices – : vector of indices of channels to be extracted;
zSliceRange – : range of z-slices to be read. Defined as a std::tuple<indexOfFirstSliceToRead,indexAfterLastSliceToRead>
timeFrameRange – : range of time frames to be read. Defined as a std::tuple<indexOfFirstTimeFrameToRead,indexAfterLastTimeFrameToRead>;
buffer – : pointer to an allocated memory buffer for the raster block. Size of the block can be computed with the method getBlockSize;
bufferSize – : size of the memory buffer in bytes.
-
void readResampled4DBlock(const std::tuple<int, int, int, int> &blockRect, const std::tuple<int, int> &blockSize, const std::tuple<int, int> &zSliceRange, const std::tuple<int, int> &timeFrameRange, void *buffer, size_t bufferSize)
reads multi-dimensional raster block to a memory buffer with resizing to the specified size.
All channels have to be of the same type. The method will throw an error by attempt to put read several channels of different types in one block. The raster will be placed in the memory buffer. The raster is organized as a continuous multi-dimensional array. Memory layout is the same as in read4DBlock method.
- Parameters:
blockRect – : rectangle of the block to be read. The rectangle is represented by std::tuple(x,y,with,height). Here:
x, y: pixel coordinates of the top left corner of the block in image coordinates (pixel shifts of the left top corner of the block;
width: block width in pixels;
height: block height in pixels; from left top corner of the image).
blockSize – : size of the block after resizing. The size is set as a std::tuple<width,height>;
zSliceRange – : range of z-slices to be read. Defined as a std::tuple<indexOfFirstSliceToRead,indexAfterLastSliceToRead>
timeFrameRange – : range of time frames to be read. Defined as a std::tuple<indexOfFirstTimeFrameToRead,indexAfterLastTimeFrameToRead>;
buffer – : pointer to an allocated memory buffer for the raster block. Size of the block can be computed with the method getBlockSize;
bufferSize – : size of the memory buffer in bytes.
-
void readResampled4DBlockChannels(const std::tuple<int, int, int, int> &blockRect, const std::tuple<int, int> &blockSize, const std::vector<int> &channelIndices, const std::tuple<int, int> &zSliceRange, const std::tuple<int, int> &timeFrameRange, void *buffer, size_t bufferSize)
reads selected channels of multi-dimensional raster block to a memory buffer with resizing to the specified size.
All channels have to be of the same type. The method will throw an error by attempt to put read several channels of different types in one block. The raster will be placed in the memory buffer. The raster is organized as a continuous multi-dimensional array. Memory layout is the same as in read4DBlock method.
- Parameters:
blockRect – : rectangle of the block to be read. The rectangle is represented by std::tuple(x,y,with,height). Here:
x, y: pixel coordinates of the top left corner of the block in image coordinates (pixel shifts of the left top corner of the block;
width: block width in pixels;
height: block height in pixels; from left top corner of the image).
blockSize – : size of the block after resizing. The size is set as a std::tuple<width,height>;
channelIndices – : vector of indices of channels to be extracted;
zSliceRange – : range of z-slices to be read. Defined as a std::tuple<indexOfFirstSliceToRead,indexAfterLastSliceToRead>
timeFrameRange – : range of time frames to be read. Defined as a std::tuple<indexOfFirstTimeFrameToRead,indexAfterLastTimeFrameToRead>;
buffer – : pointer to an allocated memory buffer for the raster block. Size of the block can be computed with the method getBlockSize;
bufferSize – : size of the memory buffer in bytes.
-
void readResampledLevelBlockChannels(int level, const std::tuple<int, int, int, int> &levelRect, const std::tuple<int, int> &blockSize, const std::vector<int> &channelIndices, void *buffer, size_t bufferSize)
reads a raster rectangle from an explicitly selected zoom level into a memory buffer.
Unlike the readBlock family, this method reads from the level named by
leveland no other, so a caller that already knows which level it wants does not have to express its rectangle in scene coordinates and let the library convert it back.Memory layout of the buffer is described in the readBlock method.
- Parameters:
level – : zoom level index, in the range [0, getNumZoomLevels()).
levelRect – : rectangle in the coordinate system of
level, as a std::tuple(x,y,width,height). The part of it outside the level is background filled.blockSize – : size of the block after resizing, as a std::tuple<width,height>. Resizing is performed from
levelonly.channelIndices – : vector of indices of channels to be extracted. Empty means all.
buffer – : pointer to an allocated memory buffer. Its size can be computed with getBlockSize using
blockSize.bufferSize – : size of the memory buffer in bytes.
-
void readResampledLevel4DBlockChannels(int level, const std::tuple<int, int, int, int> &levelRect, const std::tuple<int, int> &blockSize, const std::vector<int> &channelIndices, const std::tuple<int, int> &zSliceRange, const std::tuple<int, int> &timeFrameRange, void *buffer, size_t bufferSize)
reads a multi-dimensional raster block from an explicitly selected zoom level.
Memory layout of the buffer is described in the read4DBlock method.
- Parameters:
zSliceRange – : range of z-slices to be read, as a std::tuple<indexOfFirstSliceToRead,indexAfterLastSliceToRead>.
timeFrameRange – : range of time frames to be read. Other parameters are those of readResampledLevelBlockChannels.
-
virtual const std::list<std::string> &getAuxImageNames() const
returns array of names of auxiliary images available for the scene.
-
virtual int getNumAuxImages() const
returns number of auxiliary images available for the scene.
-
std::string getRawMetadata() const
returns string of serialized metadata. Content of the string depends on image format.
-
MetadataFormat getMetadataFormat() const
returns metadata format of the scene.
-
ColorProfile getColorProfile() const
returns the raw ICC colour profile embedded in the scene.
Empty when the slide carries none. The bytes are the profile exactly as stored, suitable for handing to an external colour management system. Use getColorProfileInfo for the parsed header.
-
ColorProfileInfo getColorProfileInfo() const
returns the parsed header of the scene’s ICC colour profile.
present is false when the slide carries no profile, and also when the profile it carries cannot be parsed. Use the source field to tell a real correction from an assumed one.
-
const Metadata &getMetadata() const
returns metadata as a navigable tree. Built lazily on first call.
-
virtual std::shared_ptr<Scene> getAuxImage(const std::string &imageName) const
returns a slideio::Scene object that represents an auxiliary image.
- Parameters:
imageName – : name of the auxiliary image.
-
int getNumZoomLevels() const
returns the number of zoom levels of the internal image pyramid.
Every scene has at least one level. Level 0 is the level of the highest resolution; the size of a level decreases with a growing level index.
-
const LevelInfo *getLevelInfo(int level) const
returns information about a zoom level of the internal image pyramid.
- Parameters:
level – : zoom level index, in the range [0, getNumZoomLevels()).
- Returns:
pointer to a slideio::LevelInfo object owned by the scene. It describes the size, scale, magnification and tile size of the level and gives access to the tile grid of the level. Use it to choose the level for readResampledLevelBlockChannels.
-
std::string toString() const
returns a human readable description of the scene.
The description contains the file path, the name, the rectangle, the channels and their data types, the number of z slices and time frames, the magnification and the number of auxiliary images and zoom levels. It is intended for logging and diagnostics; its layout is not part of the API.
-
const Metadata &getChannelAttributes() const
returns channel attributes as a Metadata tree.
Array of length getNumChannels(); each element is an Object keyed by attribute name (empty Object if a channel has no attributes).
Private Functions
Private Members
-
std::shared_ptr<CVScene> m_scene
Friends
- friend class Slide
- friend struct SceneInternal
-
inline virtual ~Scene()
-
class Scene
scenesource.hpp
-
namespace slideio
slideio: main Slideio namespace
Functions
Wraps an ISceneSource in a genuine slideio::Scene.
Performs no image work: no file is opened, nothing is cropped, no channel is selected. Every field of
metadatais reported verbatim by the corresponding Scene getter, and pixels are fetched fromsourceon demand.Throws RuntimeError if the metadata is not internally consistent – deliberately at construction, so a malformed scene fails here rather than at its first tile read.
- Parameters:
source – : supplies the pixels. Must not be null.
metadata – : what the resulting scene reports about itself.
- Returns:
a Scene usable anywhere a file backed one is, convertScene and the Python bindings included.
-
class ISceneSource
- #include <slideio/slideio/scenesource.hpp>
Supplies the pixels of a scene that is computed rather than decoded.
Implement this, describe the result in a SceneMetadata, and makeScene returns a genuine slideio::Scene that reads through it. The scene is a real Scene – it passes to convertScene, to a viewer and to the Python bindings unchanged – it is simply not backed by a file.
Public Functions
-
virtual ~ISceneSource() = default
-
virtual void readBlock(const Rect &sceneRect, const Size &blockSize, const std::vector<int> &channelIndices, int zSlice, int tFrame, void *buffer, size_t bufferSize) = 0
Reads a rectangle in SCENE coordinates, resampled to blockSize.
The one method every source must implement.
Report failure by throwing. Never by filling part of the buffer.
- Parameters:
sceneRect – : rectangle in the scene’s own coordinate system. Not clamped: SlideIO forwards it exactly as the caller gave it, so the part lying outside the scene must be filled with the background value, not omitted.
blockSize – : size of the result. Equal to sceneRect.size() means no resampling.
channelIndices – : channels to return, in the given order. Never empty: makeScene’s adapter expands “every channel” before calling, so an implementation always receives explicit indices. Duplicated indices are permitted: a channel listed more than once is delivered once per occurrence, in request order (so {0, 0} yields two copies of channel 0).
zSlice – : z slice index, 0 for a plane scene.
tFrame – : time frame index, 0 for a scene without time frames.
buffer – : destination. Row-major, channel-interleaved in the order of
channelIndices, rows contiguous with no padding, so its length is blockSize.width * blockSize.height * channel count * element size. Every requested channel shares one data type – a cv::Mat carries a single depth for all of its channels, so a mixed-type request cannot be expressed and the adapter rejects one before calling here. A scene whose channels differ in type is read one channel per call.bufferSize – : its size in bytes.
-
inline virtual bool readLevelBlock(int, const Rect&, const Size&, const std::vector<int>&, int, int, void*, size_t)
Reads from an explicitly named pyramid level, in LEVEL coordinates.
Return false – the default – to let SlideIO derive the read from readBlock by scaling through LevelInfo::getScale(), which is what CVScene does for a single level driver. Override and return true when the source has a real pyramid and reading the named level directly avoids rounding twice.
Parameters are those of readBlock, with levelRect in the coordinate system of
level. The channel contract is the same, duplicated indices included.The two paths differ in who clamps. Declining hands the read to CVScene::readClampedBlock, which clips levelRect to the level bounds, background-fills the remainder and calls readBlock with the surviving part in scene coordinates. Overriding receives levelRect unclamped and owns its own bounds handling.
-
inline virtual bool supportsConcurrentReads() const
Whether reads of one source may overlap.
False – the default – makes SlideIO serialise them, matching CVScene. Return true only if readBlock is safe to call from several threads at once.
-
inline virtual std::string getRawMetadata() const
Scene metadata as the source’s own format. Empty by default.
Read once, when makeScene builds the scene: Scene::getRawMetadata and Scene::getMetadata both report that snapshot.
-
inline virtual MetadataFormat getMetadataFormat() const
The format of getRawMetadata, which decides how Scene::getMetadata parses it.
MetadataFormat::Unknown by default, meaning “not declared”: the scene then reports MetadataFormat::Text when there is raw metadata – kept as a single “text” entry – and MetadataFormat::None when there is not, deciding from the one getRawMetadata call makeScene makes. Override to report JSON or XML and get a structured tree.
-
inline virtual std::list<std::string> getAuxImageNames() const
Names of auxiliary images. Empty by default.
Every name reported here must be served by getAuxImage.
-
inline virtual std::shared_ptr<Scene> getAuxImage(const std::string&) const
An auxiliary image by name. nullptr by default.
Return a Scene – usually one built by makeScene from a source of its own – for every name getAuxImageNames reports. nullptr makes Scene::getAuxImage throw RuntimeError for that name.
-
virtual ~ISceneSource() = default
scenemetadata.hpp
-
namespace slideio
slideio: main Slideio namespace
-
struct SceneMetadata
- #include <slideio/slideio/scenemetadata.hpp>
Everything a scene built by makeScene reports about itself.
A declaration, not a request. Each field is returned verbatim by the corresponding Scene getter: getRect() reports rect, it does not crop to it; channelNames is what getChannelName() hands back, not a selector. The pixels come from the ISceneSource handed to makeScene alongside this.
Public Members
-
std::string name
-
std::string reportedFilePath
Scene::getFilePath(). A computed scene has no file; leave it empty, or name the slide the result was derived from.
-
Rect rect
Scene::getRect(). Must match the size of level 0.
-
std::vector<std::string> channelNames
Empty, or one name per channel.
-
std::vector<int> channelSignificantBits
Empty, or one count per channel. 0 means unknown.
-
Resolution resolution = {0.0, 0.0}
Pixel size in meters.
-
double magnification = 0.0
Objective magnification. 0 if not meaningful.
-
Compression compression = Compression::Uncompressed
How the source’s pixels were stored, for reporting only.
-
int numZSlices = 1
1 for a plane scene.
-
int numTFrames = 1
1 for a scene without time frames.
-
double zSliceResolution = 0.0
Z slice thickness in meters. 0 if not meaningful.
-
double tFrameResolution = 0.0
Seconds between time frames. 0 if not meaningful.
-
std::vector<LevelInfo> levels
The pyramid, finest first. At least one entry; level 0 has scale 1 and the size of rect.
-
ColorProfile colorProfile
Empty means the scene carries no ICC profile.
-
std::string name
-
struct SceneMetadata