core module

Types shared by every module: enumerations, geometry structs, metadata, channel attribute names, colour profiles, zoom level information and exceptions. Headers are included as <slideio/core/...>.

slideio_enums.hpp

namespace slideio

slideio: main Slideio namespace

Enums

enum class Compression

raster data compression enum

Values:

enumerator Unknown

Unknown compression.

enumerator Uncompressed

Uncompressed data.

enumerator Jpeg

JPEG compression.

enumerator JpegXR

JPEG XR compression.

enumerator Png

PNG compression.

enumerator Jpeg2000

JPEG 2000 compression.

enumerator LZW

Lempel - Ziv - Welch universal lossless data compression algorithm.

enumerator HuffmanRL

RL-Huffman encoding.

enumerator CCITT_T4

CCITT T.4 2-Dimensional compression.

enumerator CCITT_T6

CCITT T.6 2-Dimensional compression.

enumerator JpegOld

Old JPEG compression algorithm.

enumerator Zlib

zlib looseless data compression

enumerator JBIG85
enumerator JBIG43
enumerator NextRLE

NeXT 2-bit RLE image compression scheme.

enumerator PackBits
enumerator ThunderScanRLE
enumerator RasterPadding
enumerator RLE_LW
enumerator RLE_HC
enumerator RLE_BL
enumerator PKZIP
enumerator KodakDCS
enumerator JBIG

JBIG early lossless image compression.

enumerator NikonNEF
enumerator JBIG2
enumerator GIF

gif image compression

enumerator BIGGIF
enumerator RLE

Run-length encoding.

enumerator BMP
enumerator JpegLossless
enumerator VP8
enum class DataType

Values:

enumerator DT_Byte
enumerator DT_Int8
enumerator DT_Int16
enumerator DT_Float16
enumerator DT_Int32
enumerator DT_Float32
enumerator DT_Float64
enumerator DT_UInt16
enumerator DT_UInt32
enumerator DT_Int64
enumerator DT_UInt64
enumerator DT_LastValid
enumerator DT_Unknown
enumerator DT_None
enum class MetadataFormat

Values:

enumerator None
enumerator Unknown
enumerator Text
enumerator JSON
enumerator XML

Functions

std::string compressionToString(Compression compression)
std::ostream &operator<<(std::ostream &os, Compression compression)
std::ostream &operator<<(std::ostream &os, const DataType &dt)
std::ostream &operator<<(std::ostream &os, const MetadataFormat &mt)

slideio_structs.hpp

rect.hpp

namespace slideio

slideio: main Slideio namespace

class Rect
#include <slideio/core/rect.hpp>

Public Functions

inline Rect()
inline Rect(int32_t _x, int32_t _y, int32_t _width, int32_t _height)
Rect(const Rect &r) = default
inline Rect(Rect &&r) noexcept
Rect(const cv::Rect &cvRect)
~Rect() = default
Rect &operator=(const Rect &r) = default
inline Rect &operator=(Rect &&r) noexcept
Rect &operator=(const cv::Rect &cvRect)
inline Size size() const
inline int64_t area() const
inline bool empty() const
inline bool valid() const

Public Members

int32_t x
int32_t y
int32_t width
int32_t height

Friends

inline friend std::ostream &operator<<(std::ostream &os, const Rect &rect)
inline friend bool operator==(const Rect &lhs, const Rect &rhs)

size.hpp

namespace slideio

slideio: main Slideio namespace

class Size
#include <slideio/core/size.hpp>

Public Functions

inline Size()
inline Size(int32_t _width, int32_t _height)
inline Size(const Size &sz)
inline Size(Size &&sz) noexcept
Size(const cv::Size &cvSize)
~Size() = default
Size &operator=(const Size &sz) = default
inline Size &operator=(Size &&sz) noexcept
Size &operator=(const cv::Size &cvSize)
inline bool operator==(const Size &other) const
inline int64_t area() const
inline bool empty() const
inline bool operator!=(const Size &size) const

Public Members

int32_t width
int32_t height

Friends

inline friend std::ostream &operator<<(std::ostream &os, const Size &size)

range.hpp

namespace slideio

slideio: main Slideio namespace

class Range
#include <slideio/core/range.hpp>

Public Functions

inline Range()
inline Range(int32_t _start, int32_t _end)
Range(const cv::Range &r)
Range(const Range &r) = default
inline Range(Range &&r) noexcept
~Range() = default
Range &operator=(const Range &r) = default
Range &operator=(const cv::Range &r)
inline Range &operator=(Range &&r) noexcept
inline int32_t size() const
inline bool empty() const
inline bool operator==(const Range &other) const
inline bool operator!=(const Range &other) const
inline Range &operator&=(const Range &r)

Public Members

int32_t start
int32_t end

Public Static Functions

static inline Range all()

Friends

inline friend Range operator&(const Range &r1, const Range &r2)
inline friend Range operator+(const Range &r, int32_t delta)
inline friend Range operator+(int32_t delta, const Range &r)
inline friend Range operator-(const Range &r, int32_t delta)
inline friend std::ostream &operator<<(std::ostream &os, const Range &range)

resolution.hpp

namespace slideio

slideio: main Slideio namespace

class Resolution
#include <slideio/core/resolution.hpp>

Public Functions

inline Resolution()
inline Resolution(double _x, double _y)
Resolution(const Resolution &pt) = default
inline Resolution(Resolution &&pt) noexcept
~Resolution() = default
Resolution &operator=(const Resolution &pt) = default
inline Resolution &operator=(Resolution &&pt) noexcept
inline bool operator==(const Resolution &pt) const

Public Members

double x
double y

levelinfo.hpp

namespace slideio

slideio: main Slideio namespace

class LevelInfo
#include <slideio/core/levelinfo.hpp>

Description of a single level of the internal image pyramid of a scene.

A scene keeps one object per zoom level and returns it from Scene::getLevelInfo. The object describes the geometry of the level: its size in the pixels of the level, the scale relative to level 0, the objective magnification and the size of the tiles the level is stored in. It also exposes the tile grid of the level through getTileCount and getTileRect, which return rectangles in the coordinate system of the level and can be passed straight to Scene::readResampledLevelBlockChannels.

Public Functions

LevelInfo() = default
inline LevelInfo(int level, const Size &size, double scale, double magnification, const Size &tileSize)
inline LevelInfo(const LevelInfo &other)
inline LevelInfo &operator=(const LevelInfo &other)
inline bool operator==(const LevelInfo &other) const
inline int computeTileCount() const

the tile count implied by the current level and tile size.

Pure: it computes and returns, and touches nothing. That is what lets getTileCount() be called from a read.

inline void updateTileCount() const

recomputes the cached tile count from the current level and tile size.

Called from the setters, which run while a scene is being built and before any read can see it. Never from a getter – see getTileCount().

inline int getLevel() const

returns the index of the level. Level 0 is the level of the highest resolution.

inline void setLevel(int level)
inline Size getSize() const

returns the size of the level in the pixels of the level.

inline void setSize(const Size &size)
inline double getScale() const

returns the scale of the level relative to level 0.

The scale of level 0 is 1; a level of half the size of level 0 has a scale of 0.5.

inline void setScale(double scale)
inline double getMagnification() const

returns the objective magnification of the level. 0 if the format does not report it.

inline void setMagnification(double magnification)
inline Size getTileSize() const

returns the size of a tile of the level. (0,0) if the level is not tiled.

inline void setTileSize(const Size &tileSize)
inline int getTileCount() const

returns the number of tiles of the level.

A level that is not tiled consists of a single tile that covers the whole level.

std::string toString() const

returns a human readable description of the level.

inline Rect getTileRect(int tileIndex) const

returns the rectangle of a tile in the coordinate system of the level.

Tiles are numbered row by row, from the top left corner of the level.

Parameters:

tileIndex – : tile index, in the range [0, getTileCount()).

Returns:

rectangle of the tile. On a level of more than one tile every rectangle has the size returned by getTileSize, so the tiles of the right and the bottom edge overhang the level; reading such a rectangle with Scene::readResampledLevelBlockChannels fills the part outside the level with the background value. On a level of a single tile the rectangle is the level itself.

Private Members

int m_level = 0
Size m_size
double m_scale = 0.0
double m_magnification = 0.0
Size m_tileSize
mutable int m_tileCount = 0

Friends

inline friend std::ostream &operator<<(std::ostream &os, const slideio::LevelInfo &levelInfo)

metadata.hpp

namespace slideio

slideio: main Slideio namespace

class Metadata
#include <slideio/core/metadata.hpp>

Read-only tree view over slide/scene metadata.

Built lazily by CVScene / CVSlide on first call to getMetadata(). Children returned by operator[] / find() are lightweight views into the same root tree and share its lifetime.

Public Types

enum class Type

Values:

enumerator Null
enumerator Bool
enumerator Int
enumerator Double
enumerator String
enumerator Array
enumerator Object

Public Functions

Metadata()
~Metadata()
Metadata(const Metadata&)
Metadata(Metadata&&) noexcept
Metadata &operator=(const Metadata&)
Metadata &operator=(Metadata&&) noexcept
Type type() const
inline bool isNull() const
inline bool isObject() const
inline bool isArray() const
bool asBool() const
int64_t asInt() const
double asDouble() const
std::string asString() const
size_t size() const
bool contains(const std::string &key) const
Metadata operator[](const std::string &key) const
Metadata operator[](size_t index) const
Metadata find(const std::string &jsonPointer) const
std::vector<std::string> keys() const
std::string toJson(int indent = -1) const

Public Static Functions

static Metadata fromImpl(std::shared_ptr<const Impl> impl)

Private Functions

explicit Metadata(std::shared_ptr<const Impl> impl)

Private Members

std::shared_ptr<const Impl> m_impl
class MetadataBuilder
#include <slideio/core/metadata.hpp>

Public Functions

MetadataBuilder()
~MetadataBuilder()
MetadataBuilder(const MetadataBuilder&)
MetadataBuilder(MetadataBuilder&&) noexcept
MetadataBuilder &operator=(const MetadataBuilder&)
MetadataBuilder &operator=(MetadataBuilder&&) noexcept
void set(const std::string &value)
void set(bool value)
void set(int64_t value)
void set(double value)
void set(const char *value)
MetadataBuilder operator[](const std::string &key)
MetadataBuilder operator[](size_t index)
void makeObject()
void makeArray()
bool isNull() const
bool isObject() const
bool isArray() const
size_t size() const
Metadata freeze() const

Public Static Functions

static MetadataBuilder fromImpl(std::shared_ptr<Impl> impl)

Private Functions

explicit MetadataBuilder(std::shared_ptr<Impl> impl)

Private Members

std::shared_ptr<Impl> m_impl

channelattributes.hpp

namespace slideio

slideio: main Slideio namespace

namespace ChannelAttribute

Names of the standard channel attributes.

Keys of the per-channel objects returned by Scene::getChannelAttributes() that carry the same meaning in every driver that sets them. A driver may add format-specific attributes under other names; these are the ones a consumer can rely on across formats.

Variables

constexpr const char *Color = "Color"

display colour of the channel, a string such as “#RRGGBB”.

constexpr const char *Name = "Name"

name of the channel, a string.

constexpr const char *EmissionWavelength = "EmissionWavelength"

emission wavelength of the channel.

constexpr const char *ExcitationWavelength = "ExcitationWavelength"

excitation wavelength of the channel.

colorprofile.hpp

namespace slideio

slideio: main Slideio namespace

Enums

enum class ColorProfileSource

where a scene’s colour profile came from

Values:

enumerator None

the file carries no profile

enumerator Embedded

a real ICC profile read out of the file

enumerator Assumed

none embedded; sRGB assumed under MissingProfilePolicy

enumerator Supplied

supplied by the caller through ColorManagement::setSourceProfileOverride rather than found in the file.

Distinct from Embedded on purpose: a supplied profile is a colorimetric claim the caller makes about the scanner, not one the slide carries. A pipeline auditing its corpus must be able to tell the two apart.

enum class IccColorSpace

colour space of ICC profile data.

Distinct from slideio::ColorSpace in the transformer, which describes OpenCV conversions and is unrelated to ICC.

Values:

enumerator Unknown
enumerator Gray
enumerator RGB
enumerator CMYK
enumerator Lab
enumerator XYZ
enumerator YCbCr
enum class RenderingIntent

ICC rendering intent.

Values:

enumerator Perceptual
enumerator RelativeColorimetric
enumerator Saturation
enumerator AbsoluteColorimetric
enum class ColorTarget

device-independent space a scene’s pixels may be converted into

Values:

enumerator sRGB
enumerator LinearRGB
enumerator Lab
enumerator XYZ
enum class MissingProfilePolicy

what to do for a slide that embeds no ICC profile.

Lives here rather than in slideio-transformer, alongside the rest of the public colour vocabulary, so it can be named – e.g. by a language binding – without pulling in ColorManagement’s own header, which is internal and drags in OpenCV.

Values:

enumerator AssumeSRGB

treat the source as sRGB. Reads always succeed; the scene reports ColorProfileSource::Assumed so absence stays visible.

enumerator PassThrough

return decoded pixels untouched. Valid only for target sRGB.

enumerator Fail

throw at bind time. For pipelines that require real colorimetry.

Functions

std::ostream &operator<<(std::ostream &os, ColorProfileSource source)
std::ostream &operator<<(std::ostream &os, IccColorSpace space)
std::ostream &operator<<(std::ostream &os, RenderingIntent intent)
std::ostream &operator<<(std::ostream &os, ColorTarget target)
class ColorProfile
#include <slideio/core/colorprofile.hpp>

raw ICC profile bytes as found in a slide.

A byte container only: it does not parse or validate its contents. Use Scene::getColorProfileInfo() for the parsed header, or hand getData() to an external colour management system. Parsing lives in slideio-imagetools because it needs lcms2, which neither this module nor any driver may see.

Public Functions

ColorProfile() = default
explicit ColorProfile(std::vector<uint8_t> iccBytes)
inline bool isEmpty() const
inline ColorProfileSource getSource() const
inline void setSource(ColorProfileSource source)
inline const std::vector<uint8_t> &getData() const
inline size_t getSize() const

Private Members

std::vector<uint8_t> m_data
ColorProfileSource m_source = ColorProfileSource::None
struct ColorProfileInfo
#include <slideio/core/colorprofile.hpp>

parsed ICC header facts. Populated by slideio-imagetools.

present gates every other field, source included. Check it first: it is false both when the scene carries no profile at all and when it carries bytes that would not parse, and in the second case source still reads Embedded – it is copied from the profile the driver stamped, not derived from a successful parse. present == false therefore means “no usable

colorimetry here”, whatever source says.

Public Functions

std::string toString() const

Public Members

bool present = false

true only if the bytes parsed as an ICC profile. See above: nothing else in this struct is meaningful when it is false.

ColorProfileSource source = ColorProfileSource::None
std::string description
std::string manufacturer
std::string model
std::string version
IccColorSpace dataSpace = IccColorSpace::Unknown
IccColorSpace connectionSpace = IccColorSpace::Unknown
RenderingIntent intent = RenderingIntent::RelativeColorimetric
std::array<double, 3> whitePoint = {0.0, 0.0, 0.0}

the profile’s mediaWhitePointTag, as XYZ.

NOT the scanner/device’s native white in general: an ICC v4 profile (icc v4 requires this per ICC.1:2010 8.2.18) always reports the PCS illuminant D50 (~0.9642, 1.0, 0.8249) here, regardless of the device’s actual white point – the device’s native white for a v4 profile is recorded separately, via the chromatic adaptation (“chad”) tag, which this struct does not expose. Only a v2 profile’s mediaWhitePointTag is the device white directly. Check version to know which case applies.

size_t dataSize = 0

exceptions.hpp

Defines

RAISE_RUNTIME_ERROR
namespace slideio

slideio: main Slideio namespace

struct RuntimeError : public std::exception
#include <slideio/core/exceptions.hpp>

Public Functions

template<typename T>
inline RuntimeError &operator<<(T rhs)
RuntimeError() = default
inline RuntimeError(RuntimeError &rhs)
inline virtual const char *what() const noexcept

Private Functions

void log(const std::string &message)

Private Members

std::stringstream m_innerStream
mutable std::string m_message
bool m_shown = false