Volumetric image data. More...

#include <vc/core/types/Volume.hpp>

Inheritance diagram for volcart::Volume:

Collaboration diagram for volcart::Volume:

Public Types
using	Bounds = BoundingBox< double, 3 >

using	Pointer = std::shared_ptr< Volume >

using	SliceItem = std::pair< cv::Mat, std::optional< mmap_info > >

using	SliceCache = Cache< int, SliceItem >

using	DefaultCache = LRUCache< int, SliceItem, NoOpMutex >

Public Types inherited from volcart::DiskBasedObjectBaseClass
using	Identifier = std::string
	Identifier type. More...

using	Description = std::pair< Identifier, std::string >

Public Member Functions

auto	sliceWidth () const -> int
	Get the slice width.

auto	sliceHeight () const -> int
	Get the slice height.

auto	numSlices () const -> int
	Get the number of slices.

auto	voxelSize () const -> double
	Get the voxel size (in microns)

auto	min () const -> double
	Get the minimum intensity value in the Volume.

auto	max () const -> double
	Get the maximum intensity value in the Volume.


void	setSliceWidth (int w)
	Set the expected width of the slice images.

void	setSliceHeight (int h)
	Set the expected height of the slice images.

void	setNumberOfSlices (std::size_t numSlices)
	Set the expected number of slice images.

void	setVoxelSize (double s)
	Set the voxel size (in microns)

void	setMin (double m)
	Set the minimum value in the Volume.

void	setMax (double m)
	Set the maximum value in the Volume.


auto	bounds () const -> Bounds
	Get the bounding box.

auto	isInBounds (double x, double y, double z) const -> bool
	Return whether a position is within the volume bounds. More...

auto	isInBounds (const cv::Vec3d &v) const -> bool


void	setMemoryMapSlices (bool b)
	Whether to memory map slices rather than loading into memory. More...

auto	getSliceData (int index) const -> cv::Mat
	Get a slice by index number. More...

auto	getSliceDataCopy (int index) const -> cv::Mat
	Get a slice by index number. More...

void	setSliceData (int index, const cv::Mat &slice, bool compress=true) const
	Set a slice by index number. More...

auto	getSlicePath (int index) const -> filesystem::path
	Get the file path of a slice by index.


auto	intensityAt (int x, int y, int z) const -> std::uint16_t
	Get the intensity value at a voxel position.

auto	intensityAt (const cv::Vec3d &v) const -> std::uint16_t
	Get the intensity value at a voxel position. More...

auto	interpolateAt (double x, double y, double z) const -> std::uint16_t
	Get the intensity value at a subvoxel position. More...

auto	interpolateAt (const cv::Vec3d &v) const -> std::uint16_t
	Get the intensity value at a subvoxel position. More...

auto	reslice (const cv::Vec3d &center, const cv::Vec3d &xvec, const cv::Vec3d &yvec, int width=64, int height=64) const -> Reslice
	Create a Reslice image by intersecting the volume with a plane. More...


void	setCacheSlices (bool b)
	Enable slice caching.

void	setCache (SliceCache::Pointer c) const
	Set the slice cache.

void	setCacheCapacity (std::size_t newCacheCapacity) const
	Set the maximum number of cached slices.

void	setCacheMemoryInBytes (std::size_t nbytes) const
	Set the maximum size of the cache in bytes.

auto	getCacheCapacity () const -> std::size_t
	Get the maximum number of cached slices.

auto	getCacheSize () const -> std::size_t
	Get the current number of cached slices.

void	cachePurge () const
	Purge the slice cache.

Public Member Functions inherited from volcart::DiskBasedObjectBaseClass
	DiskBasedObjectBaseClass ()=delete

Identifier	id () const
	Get the "unique" ID for the object.

auto	path () const -> filesystem::path
	Get the path to the object.

auto	name () const -> std::string
	Get the human-readable name for the object.

void	setName (std::string n)
	Set the human-readable name of the object.

template<typename T >
void	setMetadataEntry (const std::string &key, T value)
	Set a metadata entry. More...

template<typename T >
auto	getMetadataEntry (const std::string &key) const -> std::optional< T >
	Get a metadata entry. More...

void	saveMetadata () const
	Update metadata on disk.

Static Public Attributes
static constexpr std::size_t	DEFAULT_CAPACITY = 200

Protected Member Functions
cv::Mat	load_slice_ (int index, mmap_info *mmap_info=nullptr) const

cv::Mat	cache_slice_ (int index) const

Protected Member Functions inherited from volcart::DiskBasedObjectBaseClass
	DiskBasedObjectBaseClass (filesystem::path path)

	DiskBasedObjectBaseClass (filesystem::path path, Identifier uuid, std::string name)

Protected Attributes
int	width_ {0}

int	height_ {0}

int	slices_ {0}

int	numSliceCharacters_ {0}

bool	cacheSlices_ {true}

SliceCache::Pointer	cache_ {DefaultCache::New(DEFAULT_CAPACITY)}

std::shared_mutex	cacheMutex_

std::vector< std::mutex >	sliceMutexes_

bool	memmap_ {true}

Protected Attributes inherited from volcart::DiskBasedObjectBaseClass
Metadata	metadata_

filesystem::path	path_

	Volume ()=delete

	Volume (filesystem::path path)
	Load the Volume from a directory path.

	Volume (filesystem::path path, Identifier uuid, std::string name)
	Make a new Volume at the specified path.

static auto	New (const filesystem::path &path) -> Pointer

static auto	New (const filesystem::path &path, const Identifier &uuid, const std::string &name) -> Pointer

Detailed Description

Volumetric image data.

Author: Sean Karlage

Provides access to a volumetric dataset, such as a CT scan. By default, slices are cached in memory using volcart::LRUCache.

Definition at line 34 of file Volume.hpp.

Member Typedef Documentation

◆ Bounds

using volcart::Volume::Bounds = BoundingBox<double, 3>

Bounding Box type

Definition at line 39 of file Volume.hpp.

◆ DefaultCache

using volcart::Volume::DefaultCache = LRUCache<int, SliceItem, NoOpMutex>

Default slice cache type

Definition at line 51 of file Volume.hpp.

◆ Pointer

using volcart::Volume::Pointer = std::shared_ptr<Volume>

Shared pointer type

Definition at line 42 of file Volume.hpp.

◆ SliceCache

using volcart::Volume::SliceCache = Cache<int, SliceItem>

Slice cache type

Definition at line 48 of file Volume.hpp.

◆ SliceItem

using volcart::Volume::SliceItem = std::pair<cv::Mat, std::optional<mmap_info> >

Slice item type

Definition at line 45 of file Volume.hpp.

Constructor & Destructor Documentation

◆ Volume()

volcart::Volume::Volume ( )

delete

Default constructor. Cannot be constructed without path.

Member Function Documentation

◆ cache_slice_()

cv::Mat volcart::Volume::cache_slice_ ( int index ) const

protected

Load slice from cache

◆ getSliceData()

auto volcart::Volume::getSliceData ( int index ) const -> cv::Mat

Get a slice by index number.

Warning: Because cv::Mat is essentially a pointer to a matrix, modifying the slice returned by getSliceData() will modify the cached slice as well. Use getSliceDataCopy() if the slice is to be modified.

◆ getSliceDataCopy()

auto volcart::Volume::getSliceDataCopy ( int index ) const -> cv::Mat

Get a slice by index number.

Warning: Because cv::Mat is essentially a pointer to a matrix, modifying the slice returned by getSliceData() will modify the cached slice as well. Use getSliceDataCopy() if the slice is to be modified.

◆ intensityAt()

auto volcart::Volume::intensityAt ( const cv::Vec3d & v ) const -> std::uint16_t

Get the intensity value at a voxel position.

◆ interpolateAt() [1/2]

auto volcart::Volume::interpolateAt ( const cv::Vec3d & v ) const -> std::uint16_t

Get the intensity value at a subvoxel position.

Values are trilinearly interpolated.

Trilinear interpolation equation from here.

◆ interpolateAt() [2/2]

auto volcart::Volume::interpolateAt	(	double	x,
		double	y,
		double	z
	)		const -> std::uint16_t

Get the intensity value at a subvoxel position.

Values are trilinearly interpolated.

Trilinear interpolation equation from here.

◆ isInBounds()

volcart::Volume::isInBounds	(	double	x,
		double	y,
		double	z
	)		const -> bool

Return whether a position is within the volume bounds.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ load_slice_()

cv::Mat volcart::Volume::load_slice_	(	int	index,
		mmap_info *	mmap_info = `nullptr`
	)		const

protected

Load slice from disk

◆ reslice()

auto volcart::Volume::reslice	(	const cv::Vec3d &	center,
		const cv::Vec3d &	xvec,
		const cv::Vec3d &	yvec,
		int	width = `64`,
		int	height = `64`
	)		const -> Reslice

Create a Reslice image by intersecting the volume with a plane.

Warning: This function makes no attempt to check that the X and Y vectors are orthogonal to each other. Vectors that are not orthogonal will produce unexpected behavior.

Parameters

center	Center of the Reslice image
xvec	X-axis of the Reslice plane
yvec	Y-axis of the Reslice plane
height	Height of the Reslice image
width	Width of the Reslice image

◆ setMemoryMapSlices()

void volcart::Volume::setMemoryMapSlices ( bool b )

Whether to memory map slices rather than loading into memory.

When enabled, the Volume will attempt to memory map slice images rather than reading them into memory. This is currently only supported when slice caching is enabled as well.

Slices which are already cached will not be affected by this change.

◆ setSliceData()

void volcart::Volume::setSliceData	(	int	index,
		const cv::Mat &	slice,
		bool	compress = `true`
	)		const

Set a slice by index number.

Index must be less than the number of slices in the volume.

Warning: This will overwrite any existing slice data on disk.

Member Data Documentation

◆ cache_

SliceCache::Pointer volcart::Volume::cache_ {DefaultCache::New(DEFAULT_CAPACITY)}

mutableprotected

Slice cache

Definition at line 230 of file Volume.hpp.

◆ cacheMutex_

std::shared_mutex volcart::Volume::cacheMutex_

mutableprotected

Cache mutex for thread-safe access

Definition at line 232 of file Volume.hpp.

◆ cacheSlices_

bool volcart::Volume::cacheSlices_ {true}

protected

Whether to use slice cache

Definition at line 228 of file Volume.hpp.

◆ DEFAULT_CAPACITY

constexpr std::size_t volcart::Volume::DEFAULT_CAPACITY = 200

staticconstexpr

Default slice cache capacity

Definition at line 54 of file Volume.hpp.

◆ height_

int volcart::Volume::height_ {0}

protected

Slice height

Definition at line 221 of file Volume.hpp.

◆ memmap_

bool volcart::Volume::memmap_ {true}

protected

Whether to memmap slices

Definition at line 238 of file Volume.hpp.

◆ numSliceCharacters_

int volcart::Volume::numSliceCharacters_ {0}

protected

Slice file name padding

Definition at line 225 of file Volume.hpp.

◆ sliceMutexes_

std::vector<std::mutex> volcart::Volume::sliceMutexes_

mutableprotected

Per-slice mutexes

Definition at line 235 of file Volume.hpp.

◆ slices_

int volcart::Volume::slices_ {0}

protected

Number of slices

Definition at line 223 of file Volume.hpp.

◆ width_

int volcart::Volume::width_ {0}

protected

Slice width

Definition at line 219 of file Volume.hpp.

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

vc/core/types/Volume.hpp

Public Types

Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ Bounds

◆ DefaultCache

◆ Pointer

◆ SliceCache

◆ SliceItem

Constructor & Destructor Documentation

◆ Volume()

Member Function Documentation

◆ cache_slice_()

◆ getSliceData()

◆ getSliceDataCopy()

◆ intensityAt()

◆ interpolateAt() [1/2]

◆ interpolateAt() [2/2]

◆ isInBounds()

◆ load_slice_()

◆ reslice()

◆ setMemoryMapSlices()

◆ setSliceData()

Member Data Documentation

◆ cache_

◆ cacheMutex_

◆ cacheSlices_

◆ DEFAULT_CAPACITY

◆ height_

◆ memmap_

◆ numSliceCharacters_

◆ sliceMutexes_

◆ slices_

◆ width_