The interface to the VolumePkg (.volpkg) file format. More...

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

Collaboration diagram for volcart::VolumePkg:

Public Member Functions
Metadata
auto	name () const -> std::string
	Returns the identifying name of the VolumePkg. More...

auto	version () const -> int
	Returns the VolumePkg version. More...

auto	materialThickness () const -> double
	Returns the approx. thickness of a material layer in microns (um). More...

auto	metadata () const -> Metadata
	Return the VolumePkg Metadata.

template<typename T >
void	setMetadata (const std::string &key, T value)
	Sets the value of `key` in the VolumePkg metadata. More...

void	saveMetadata () const
	Saves the metadata to the VolumePkg (.volpkg) file.

void	saveMetadata (const filesystem::path &filePath) const
	Saves the metadata to a user-specified location. More...

Volume Data
auto	hasVolumes () const -> bool
	Return whether there are Volumes.

auto	hasVolume (const Volume::Identifier &id) const -> bool
	Whether a volume with the given identifier is in the VolumePkg.

auto	numberOfVolumes () const -> std::size_t
	Get the number of Volumes.

auto	volumeIDs () const -> std::vector< Volume::Identifier >
	Get the list of volume IDs.

auto	volumeNames () const -> std::vector< std::string >
	Get the list of volumes names.

auto	newVolume (std::string name="") -> Volume::Pointer
	Add a new Volume to the VolumePkg. More...

auto	volume () const -> Volume::Pointer
	Get the first Volume.

auto	volume () -> Volume::Pointer
	Get the first Volume. More...

auto	volume (const Volume::Identifier &id) const -> Volume::Pointer
	Get a Volume by uuid.

auto	volume (const Volume::Identifier &id) -> Volume::Pointer
	Get a Volume by uuid. More...

Segmentation Data
auto	hasSegmentations () const -> bool
	Return whether there are Segmentations.

auto	numberOfSegmentations () const -> std::size_t
	Get the number of Segmentations.

auto	segmentationIDs () const -> std::vector< Segmentation::Identifier >
	Get the list of Segmentation IDs.

auto	segmentationNames () const -> std::vector< std::string >
	Get the list of Segmentation names.

auto	newSegmentation (std::string name="") -> Segmentation::Pointer
	Creates a new segmentation. More...

auto	removeSegmentation (const Segmentation::Identifier &id) -> bool
	Removes an existing segmentation. More...

auto	segmentation (const Segmentation::Identifier &id) const -> Segmentation::Pointer
	Get a Segmentation by uuid.

auto	segmentation (const Segmentation::Identifier &id) -> Segmentation::Pointer
	Get a Segmentation by uuid. More...

Render Data
auto	hasRenders () const -> bool
	Return whether there are Renders.

auto	numberOfRenders () const -> std::size_t
	Get the number of Renders.

auto	renderIDs () const -> std::vector< Render::Identifier >
	Get the list of Render IDs.

auto	renderNames () const -> std::vector< std::string >
	Get the list of Render names.

auto	newRender (std::string name="") -> Render::Pointer
	Creates a new Render. More...

auto	render (const Render::Identifier &id) const -> Render::Pointer
	Get a Render by uuid.

auto	render (const Render::Identifier &id) -> Render::Pointer
	Get a Render by uuid. More...

Transform Data
auto	hasTransforms () const -> bool
	Return whether there are transforms in the VolumePkg.

auto	hasTransform (const Transform3D::Identifier &id) const -> bool
	Return whether a transform with the given identifier is in the VolumePkg. More...

auto	addTransform (const Transform3D::Pointer &transform) -> Transform3D::Identifier
	Add a transform to the VolPkg.

void	setTransform (const Transform3D::Identifier &id, const Transform3D::Pointer &transform)
	Replace an existing transform.

auto	transform (Transform3D::Identifier id) const -> Transform3D::Pointer
	Get a transform by ID. More...

auto	transform (const Volume::Identifier &src, const Volume::Identifier &tgt) const -> std::vector< std::pair< Transform3D::Identifier, Transform3D::Pointer > >
	Get a list of transforms (possibly composite transforms) which map from a source volume to a target volume. More...

auto	transformIDs () const -> std::vector< Transform3D::Identifier >
	Get the list of transform IDs.

Static Public Member Functions
static void	Upgrade (const filesystem::path &path, int version=VOLPKG_VERSION_LATEST, bool force=false)

Static Private Member Functions
static auto	InitConfig (const Dictionary &dict, int version) -> Metadata
	Populates an empty VolumePkg::config from a volcart::Dictionary template. More...

Private Attributes
Metadata	config_

filesystem::path	rootDir_

std::map< Volume::Identifier, Volume::Pointer >	volumes_

std::map< Segmentation::Identifier, Segmentation::Pointer >	segmentations_

std::map< Render::Identifier, Render::Pointer >	renders_

std::map< Transform3D::Identifier, Transform3D::Pointer >	transforms_

using	Pointer = std::shared_ptr< VolumePkg >

	VolumePkg (filesystem::path path, int version)
	Construct an empty VolumePkg of a specific version number. More...

	VolumePkg (const filesystem::path &path)
	Construct a VolumePkg from a .volpkg file stored at `fileLocation.` More...

static auto	New (const filesystem::path &path, int version) -> Pointer
	Construct an empty VolumePkg of a specific version number. More...

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

Detailed Description

The interface to the VolumePkg (.volpkg) file format.

Provides access to volume, segmentation, and rendering data stored on disk.

Warning: VolumePkg is not thread safe.

See also: apps/src/packager.cpp apps/src/metadata.cpp examples/src/volpkg.cpp examples/src/ResliceAnalysis.cpp

Definition at line 36 of file VolumePkg.hpp.

Member Typedef Documentation

◆ Pointer

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

VolumePkg shared pointer

Definition at line 61 of file VolumePkg.hpp.

Constructor & Destructor Documentation

◆ VolumePkg() [1/2]

volcart::VolumePkg::VolumePkg	(	filesystem::path	path,
		int	version
	)

Construct an empty VolumePkg of a specific version number.

This will construct an empty VolumePkg in memory and set its expected location on disk. Note: You must call initialize() before the file can be written to and accessed. Only metadata keys may be modified before initialize is called.

Parameters

path	The location to store the VolPkg
version	Version of VolumePkg you wish to construct

◆ VolumePkg() [2/2]

volcart::VolumePkg::VolumePkg ( const filesystem::path & path )

explicit

Construct a VolumePkg from a .volpkg file stored at fileLocation.

Parameters

path	The root of the VolumePkg file

Member Function Documentation

◆ hasTransform()

auto volcart::VolumePkg::hasTransform ( const Transform3D::Identifier & id ) const -> bool

Return whether a transform with the given identifier is in the VolumePkg.

If the provided identifier ends with "*", additionally checks if the transform can be inverted. Supports transform paths using the -> operator.

See also: VolumePkg::transform(Transform3D::Identifier)

◆ InitConfig()

static auto volcart::VolumePkg::InitConfig	(	const Dictionary &	dict,
		int	version
	)		-> Metadata

staticprivate

Populates an empty VolumePkg::config from a volcart::Dictionary template.

The configuration is populated with all keys found in dict. This is not validated against what is expected for the passed version number.

Parameters

dict	Metadata template
version	Version number of the passed Dictionary

Returns: volcart::Metadata populated with default keys

◆ materialThickness()

auto volcart::VolumePkg::materialThickness ( ) const -> double

Returns the approx. thickness of a material layer in microns (um).

This value is approximated by the user when the VolumePkg is created. This is an intrinsic property of the scanned object and is therefore indepedent of scan resolution. The material thickness in microns can be used to estimate the material thickness in voxels for scans of any resolution.

$\frac{\mbox{Material Thickness }(um)}{\mbox{Voxel Size }(um)} = \mbox{Material Thickness }(voxels)$

Returns: Layer thickness, measured in microns (um).

◆ name()

auto volcart::VolumePkg::name ( ) const -> std::string

Returns the identifying name of the VolumePkg.

Returns: Name of the VolumePkg

◆ New() [1/2]

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

static

Returns a shared pointer to the VolumePkg.

◆ New() [2/2]

static auto volcart::VolumePkg::New	(	const filesystem::path &	path,
		int	version
	)		-> Pointer

static

Construct an empty VolumePkg of a specific version number.

Returns a shared pointer to the VolumePkg.

◆ newRender()

auto volcart::VolumePkg::newRender ( std::string name = "" ) -> Render::Pointer

Creates a new Render.

Populates the .volpkg file with a new Render directory and adds the ID to the internal list of Renders.

◆ newSegmentation()

auto volcart::VolumePkg::newSegmentation ( std::string name = "" ) -> Segmentation::Pointer

Creates a new segmentation.

Populates the .volpkg file with a new segmentation directory and adds the ID to the internal list of segmentations.

Returns: Identifier name of the new segmentation

◆ newVolume()

auto volcart::VolumePkg::newVolume ( std::string name = "" ) -> Volume::Pointer

Add a new Volume to the VolumePkg.

Parameters

name	Human-readable name for the new Volume. Defaults to the auto-generated Volume ID.

Returns: Pointer to the new Volume

◆ removeSegmentation()

auto volcart::VolumePkg::removeSegmentation ( const Segmentation::Identifier & id ) -> bool

Removes an existing segmentation.

Returns false and prints to Logger() if removal fails for any reason:

Warning
- Empty ID
- ID not in internal map
- Segmentation directory does not exist
Error
- Filsystem error when deleting the segmentation directory. Segmentation directory may have been partially removed.
- Failed to remove segmentation from internal map.

Returns: If removal was successful

◆ render()

auto volcart::VolumePkg::render ( const Render::Identifier & id ) -> Render::Pointer

Get a Render by uuid.

◆ saveMetadata()

void volcart::VolumePkg::saveMetadata ( const filesystem::path & filePath ) const

Saves the metadata to a user-specified location.

Parameters

filePath Path to output file

◆ segmentation()

auto volcart::VolumePkg::segmentation ( const Segmentation::Identifier & id ) -> Segmentation::Pointer

Get a Segmentation by uuid.

◆ setMetadata()

template<typename T >

void volcart::VolumePkg::setMetadata	(	const std::string &	key,
		T	value
	)

inline

Sets the value of key in the VolumePkg metadata.

These values are stored only in memory until saveMetadata() is called.

Parameters

key	Metadata key identifier
value	Value to be stored

Definition at line 127 of file VolumePkg.hpp.

◆ transform() [1/2]

auto volcart::VolumePkg::transform	(	const Volume::Identifier &	src,
		const Volume::Identifier &	tgt
	)		const -> std::vector< std::pair< Transform3D::Identifier, Transform3D::Pointer > >

Get a list of transforms (possibly composite transforms) which map from a source volume to a target volume.

Runs breadth-first search (BFS) to find the shortest transform paths from the source to target volume. Single-transform paths are returned as their original transform type (e.g. AffineTransform, IdentityTransform). Multi-transform paths are returned as a new, unsimplified CompositeTransform. Paths are returned in order of increasing length and may include inverse transforms which satisfy the mapping.

The current implementation does not return all transform paths, but prunes cycles and paths which would use transforms that are already part of a shorter path.

◆ transform() [2/2]

auto volcart::VolumePkg::transform ( Transform3D::Identifier id ) const -> Transform3D::Pointer

Get a transform by ID.

If the provided ID ends with *, returns the inverse transform. Transform paths can be constructed with the -> operator and will be returned as a composite transform:

vpkg->transform("id1->id2->id3*");

The source and target properties of the returned CompositeTransform is set to the source of the first transform and the target of the final transform (post-inversion), but the intermediate path is not verified.

◆ Upgrade()

static void volcart::VolumePkg::Upgrade	(	const filesystem::path &	path,
		int	version = `VOLPKG_VERSION_LATEST`,
		bool	force = `false`
	)

static

Utility function for updating VolumePkgs

◆ version()

auto volcart::VolumePkg::version ( ) const -> int

Returns the VolumePkg version.

Use in conjunction with volcart::VERSION_LIBRARY to verify the presence of specific VolumePkg metadata keys.

Returns: Version number of VolumePkg

◆ volume() [1/2]

auto volcart::VolumePkg::volume ( ) -> Volume::Pointer

Get the first Volume.

◆ volume() [2/2]

auto volcart::VolumePkg::volume ( const Volume::Identifier & id ) -> Volume::Pointer

Get a Volume by uuid.

Member Data Documentation

◆ config_

Metadata volcart::VolumePkg::config_

private

VolumePkg metadata

Definition at line 341 of file VolumePkg.hpp.

◆ renders_

std::map<Render::Identifier, Render::Pointer> volcart::VolumePkg::renders_

private

The list of all Renders in the VolumePkg.

Definition at line 349 of file VolumePkg.hpp.

◆ rootDir_

filesystem::path volcart::VolumePkg::rootDir_

private

The root directory of the VolumePkg

Definition at line 343 of file VolumePkg.hpp.

◆ segmentations_

std::map<Segmentation::Identifier, Segmentation::Pointer> volcart::VolumePkg::segmentations_

private

The list of all Segmentations in the VolumePkg.

Definition at line 347 of file VolumePkg.hpp.

◆ transforms_

std::map<Transform3D::Identifier, Transform3D::Pointer> volcart::VolumePkg::transforms_

private

The list of Transforms in the VolumePkg

Definition at line 351 of file VolumePkg.hpp.

◆ volumes_

std::map<Volume::Identifier, Volume::Pointer> volcart::VolumePkg::volumes_

private

The list of all Volumes in the VolumePkg.

Definition at line 345 of file VolumePkg.hpp.

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

vc/core/types/VolumePkg.hpp

Public Member Functions

Static Public Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ Pointer

Constructor & Destructor Documentation

◆ VolumePkg() [1/2]

◆ VolumePkg() [2/2]

Member Function Documentation

◆ hasTransform()

◆ InitConfig()

◆ materialThickness()

◆ name()

◆ New() [1/2]

◆ New() [2/2]

◆ newRender()

◆ newSegmentation()

◆ newVolume()

◆ removeSegmentation()

◆ render()

◆ saveMetadata()

◆ segmentation()

◆ setMetadata()

◆ transform() [1/2]

◆ transform() [2/2]

◆ Upgrade()

◆ version()

◆ volume() [1/2]

◆ volume() [2/2]

Member Data Documentation

◆ config_

◆ renders_

◆ rootDir_

◆ segmentations_

◆ transforms_

◆ volumes_