Scene class represents a raster image contained in a slide. More...

#include <scene.hpp>

Public Member Functions
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. More...

int	getNumChannels () const
	returns number of raster channels of the image

int	getNumZSlices () const
	returns number of slices for 3D/4D images. More...

int	getNumTFrames () const
	returns number of time frames for 3D/4D images. More...

Compression	getCompression () const
	returns compression of the raster data

slideio::DataType	getChannelDataType (int channel) const

std::string	getChannelName (int channel) const
	returns channel name. More...

std::tuple< double, double >	getResolution () const
	returns image resolution in x and y direction. More...

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.

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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.

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. More...

int	getNumZoomLevels () const
	returns the number of zoom levels of the internal image pyramid. More...

const LevelInfo *	getLevelInfo (int level) const
	returns information about a zoom level of the internal image pyramid. More...

std::string	toString () const
	returns a human readable description of the scene. More...

const Metadata &	getChannelAttributes () const
	returns channel attributes as a Metadata tree. More...

Detailed Description

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.

Member Function Documentation

◆ getAuxImage()

std::shared_ptr< Scene > Scene::getAuxImage ( const std::string & imageName ) const

virtual

returns a slideio::Scene object that represents an auxiliary image.

Parameters

imageName : name of the auxiliary image.

◆ getBlockSize()

int Scene::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;

◆ getChannelAttributes()

const slideio::Metadata & Scene::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).

◆ getChannelDataType()

slideio::DataType Scene::getChannelDataType ( int channel ) const

brief returns data type of a channel

Parameters

channel : index of the channel. Should be in the range (0, numberOfChannels)

◆ getChannelName()

std::string Scene::getChannelName ( int channel ) const

returns channel name.

Parameters

channel : index of the channel. Should be in the range (0, numberOfChannels)

◆ getLevelInfo()

const LevelInfo * Scene::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.

◆ getNumTFrames()

int Scene::getNumTFrames ( ) const

returns number of time frames for 3D/4D images.

The method returns 1 for images without time frames.

◆ getNumZoomLevels()

int Scene::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.

◆ getNumZSlices()

int Scene::getNumZSlices ( ) const

returns number of slices for 3D/4D images.

The method returns 1 for 2D images.

◆ getRect()

std::tuple< int, int, int, int > Scene::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.

◆ getResolution()

std::tuple< double, double > Scene::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.

◆ read4DBlock()

void Scene::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.

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.

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.

DataType raster[numberOfTimeFramesToRead][numberOfzSlicesToRead][numberOfBlockRows][numberOfBlockColumns][numberOfBlockChannels];

where:

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];

◆ read4DBlockChannels()

void Scene::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.

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.

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.

◆ readBlock()

void Scene::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.

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.

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.

DataType raster[numberOfRows][numberOfColumns][numberOfChannels];

where:

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];

◆ readBlockChannels()

void Scene::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.

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.

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.

◆ readResampled4DBlock()

void Scene::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.

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.

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.

◆ readResampled4DBlockChannels()

void Scene::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.

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.

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.

◆ readResampledBlock()

void Scene::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.

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.

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

bufferSize : size of the memory buffer in bytes.

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.

◆ readResampledBlockChannels()

void Scene::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.

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.

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

bufferSize : size of the memory buffer in bytes.

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.

◆ readResampledLevel4DBlockChannels()

void Scene::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.

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.

Memory layout of the buffer is described in the read4DBlock method.

◆ readResampledLevelBlockChannels()

void Scene::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 level and 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.

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 `level` only.
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.

Memory layout of the buffer is described in the readBlock method.

◆ toString()

std::string Scene::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.

The documentation for this class was generated from the following files:

src/slideio/slideio/scene.hpp
src/slideio/slideio/scene.cpp

Public Member Functions

Detailed Description

Member Function Documentation

◆ getAuxImage()

◆ getBlockSize()

◆ getChannelAttributes()

◆ getChannelDataType()

◆ getChannelName()

◆ getLevelInfo()

◆ getNumTFrames()

◆ getNumZoomLevels()

◆ getNumZSlices()

◆ getRect()

◆ getResolution()

◆ read4DBlock()

◆ read4DBlockChannels()

◆ readBlock()

◆ readBlockChannels()

◆ readResampled4DBlock()

◆ readResampled4DBlockChannels()

◆ readResampledBlock()

◆ readResampledBlockChannels()

◆ readResampledLevel4DBlockChannels()

◆ readResampledLevelBlockChannels()

◆ toString()