Volume Cartographer 2.27.0
Static Public Member Functions | Static Private Member Functions | Private Attributes | List of all members
volcart::VolumePkg Class Reference

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

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

Collaboration diagram for volcart::VolumePkg:
[legend]

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::Pointervolumes_
 
std::map< Segmentation::Identifier, Segmentation::Pointersegmentations_
 
std::map< Render::Identifier, Render::Pointerrenders_
 
std::map< Transform3D::Identifier, Transform3D::Pointertransforms_
 
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
pathThe location to store the VolPkg
versionVersion 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
pathThe 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
dictMetadata template
versionVersion 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
nameHuman-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
filePathPath 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,
value 
)
inline

Sets the value of key in the VolumePkg metadata.

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

Parameters
keyMetadata key identifier
valueValue 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: