The base class for all 3 dimensional shapes. More...

#include "stir/Shape/Shape3D.h"

Inheritance diagram for stir::Shape3D:

[legend]

Public Member Functions
virtual bool	operator== (const Shape3D &) const =0
	Compare shapes.

bool	operator!= (const Shape3D &) const
	Compare shapes.

virtual float	get_voxel_weight (const CartesianCoordinate3D< float > &voxel_centre, const CartesianCoordinate3D< float > &voxel_size, const CartesianCoordinate3D< int > &num_samples) const
	Determine (approximately) the intersection volume of a voxel with the shape.

virtual bool	is_inside_shape (const CartesianCoordinate3D< float > &coord) const =0
	determine if a point is inside the shape or not (up to floating point errors)

virtual void	translate (const CartesianCoordinate3D< float > &direction)
	translate the whole shape by shifting its origin

virtual void	scale (const CartesianCoordinate3D< float > &scale3D)=0
	scale the whole shape

void	scale_around_origin (const CartesianCoordinate3D< float > &scale3D)
	scale the whole shape, keeping the centre at the same place

virtual void	construct_volume (VoxelsOnCartesianGrid< float > &image, const CartesianCoordinate3D< int > &num_samples) const
	construct an image representation the shape in a discretised manner

virtual float	get_geometric_volume () const
	Compute approximate volume.

CartesianCoordinate3D< float >	get_origin () const
	get the origin of the shape-coordinate system

virtual void	set_origin (const CartesianCoordinate3D< float > &)
	set the origin of the shape-coordinate system

virtual Shape3D *	clone () const =0
	Allocate a new Shape3D object which is a copy of the current one.

std::string	parameter_info () override

Public Member Functions inherited from stir::RegisteredObjectBase
virtual std::string	get_registered_name () const =0
	Returns the name of the type of the object.

Public Member Functions inherited from stir::ParsingObject
	ParsingObject (const ParsingObject &)

ParsingObject &	operator= (const ParsingObject &)

bool	parse (std::istream &f)

bool	parse (const char *const filename)

void	ask_parameters ()

Protected Member Functions
	Shape3D (const CartesianCoordinate3D< float > &origin)

virtual bool	post_processing ()
	This will be called at the end of the parsing.

virtual void	set_key_values ()
	This will be called before parsing or parameter_info is called.

Parsing functions
void	set_defaults () override
	Set defaults before parsing.

void	initialise_keymap () override
	Initialise all keywords.

Additional Inherited Members
Static Public Member Functions inherited from stir::RegisteredObject< Shape3D >
static Shape3D *	read_registered_object (std::istream *in, const std::string &registered_name)
	Construct a new object (of a type derived from Root, its actual type determined by the registered_name parameter) by parsing the istream.

static Shape3D *	ask_type_and_parameters ()
	ask the user for the type, and then calls read_registered_object(0, type)

static void	list_registered_names (std::ostream &stream)
	List all possible registered names to the stream.

Protected Types inherited from stir::RegisteredObject< Shape3D >
typedef Shape3D (	RootFactory) (std::istream *)
	The type of a root factory is a function, taking an istream* as argument, and returning a Root*.

typedef FactoryRegistry< std::string, RootFactory, interfile_less >	RegistryType
	The type of the registry.

Static Protected Member Functions inherited from stir::RegisteredObject< Shape3D >
static RegistryType &	registry ()
	Static function returning the registry.

KeyParser	parser

Detailed Description

The base class for all 3 dimensional shapes.

Shape3D objects are intended to represent geometrical object with sharp boundaries. So, a point is inside or shape, or it is not (i.e. no fuzzyness).

The only derived class where this is relaxed is DiscretisedShape3D. However, this then needs some special treatment for some member functions, and you have to be somewhat careful with that class.

Todo: This could/should be generalised to allow general fuzzy shapes. Probably the only thing to change is to let is_inside_shape() return a float (between 0 and 1). This would solve some issues with DiscretisedDhape3D.

Todo: The restriction to the 3D case for this base class largely comes from the construct_volume() member (and the origin parsing members)

Todo: This base class really should have no origin member. For example, DiscretisedShape3D now has effectively two. Instead, we should have an additional class Shape3DWithOrigin. Easy to do.

Parsing

This base class defines the following keywords for parsing

; specify origin as {z,y,x}
origin (in mm):= <float> ;defaults to {0,0,0}

Member Function Documentation

◆ operator==()

bool stir::Shape3D::operator== ( const Shape3D & s ) const

inlinepure virtual

Compare shapes.

Implementation note

This virtual function has to be implemented in each final class of the hierarchy. However, Shape3D::operator== has an implementation that checks equality of the origin (up-to a tolerance of .001). Derived classes can call this implementation.

Implemented in stir::Box3D, stir::DiscretisedShape3D, stir::Ellipsoid, stir::EllipsoidalCylinder, and stir::Shape3DWithOrientation.

References stir::norm(), and operator==().

Referenced by operator==(), and stir::Shape3DWithOrientation::operator==().

◆ get_voxel_weight()

float stir::Shape3D::get_voxel_weight	(	const CartesianCoordinate3D< float > &	voxel_centre,
		const CartesianCoordinate3D< float > &	voxel_size,
		const CartesianCoordinate3D< int > &	num_samples ) const

virtual

Determine (approximately) the intersection volume of a voxel with the shape.

Parameters

voxel_centre	is a cartesian coordinate in 'absolute' coordinates, i.e. in mm and not relative to the origin member.
voxel_size	is the voxel size in mm.
num_samples	determines the number of samples to take in z,y,x direction.

Returns: a value between 0 and 1 representing the fraction of the voxel inside the shape

In the Shape3D implementation, this is simply done by calling is_inside_shape() at various points in the voxel, and returning the average value. Obviously, this will only approximate the intersection volume for very large num_samples, or when the voxel is completely inside the shape.

Reimplemented in stir::DiscretisedShape3D.

References get_voxel_weight(), and is_inside_shape().

Referenced by construct_volume(), and get_voxel_weight().

◆ is_inside_shape()

virtual bool stir::Shape3D::is_inside_shape ( const CartesianCoordinate3D< float > & coord ) const

pure virtual

determine if a point is inside the shape or not (up to floating point errors)

Parameters

coord is a cartesian coordinate in 'absolute' coordinates, i.e. in mm and not relative to the origin member.

This is really only well defined for shapes with sharp boundaries.

See also: DiscretisedShape3D::is_inside_shape for some discussion.

Todo: replace by floating point return value?

Implemented in stir::Box3D, stir::CombinedShape3D< operation >, stir::DiscretisedShape3D, stir::Ellipsoid, and stir::EllipsoidalCylinder.

References translate().

Referenced by construct_volume(), and get_voxel_weight().

◆ translate()

void stir::Shape3D::translate ( const CartesianCoordinate3D< float > & direction )

virtual

translate the whole shape by shifting its origin

Uses set_origin().

See also: scale()

Reimplemented in stir::CombinedShape3D< operation >.

References get_origin(), set_origin(), and translate().

Referenced by is_inside_shape(), scale_around_origin(), and translate().

◆ scale()

virtual void stir::Shape3D::scale ( const CartesianCoordinate3D< float > & scale3D )

pure virtual

scale the whole shape

Scaling the shape also shifts the origin of the shape: new_origin = old_origin * scale3D. This is necessary such that combined shapes keep their correct relative positions. This means that scaling and translating is non-commutative.

shape1=shape;
shape1.translate(offset); shape1.scale(scale);
shape2=shape;
shape2.scale(scale); shape2.translate(offset*scale);
assert(shape1==shape2);

Implemented in stir::CombinedShape3D< operation >, stir::DiscretisedShape3D, and stir::Shape3DWithOrientation.

References construct_volume(), get_geometric_volume(), get_origin(), scale_around_origin(), and set_origin().

Referenced by scale_around_origin().

◆ construct_volume()

void stir::Shape3D::construct_volume	(	VoxelsOnCartesianGrid< float > &	image,
		const CartesianCoordinate3D< int > &	num_samples ) const

virtual

construct an image representation the shape in a discretised manner

In principle, each voxel is sub-sampled to allow smoother edges.

Warning: Shapes have to be larger than the voxel size for sensible results. For efficiency reasons, the current implementation of this function does a first pass through the image where is_inside_shape() is called only for the centre of the voxels. After this, only edge voxels are resampled. So, if a shape lies between the centre of all voxels, it will not be sampled at all.

Todo

Get rid of restriction to allow only VoxelsOnCartesianGrid<float> (but that's rather hard)

Potentially this should fill a DiscretisedShape3D.

Reimplemented in stir::DiscretisedShape3D.

References construct_volume(), stir::DiscretisedDensity< num_dimensions, elemT >::get_origin(), stir::VoxelsOnCartesianGrid< elemT >::get_voxel_size(), get_voxel_weight(), stir::info(), and is_inside_shape().

Referenced by stir::ReconstructionTests< TargetT >::construct_input_data(), construct_volume(), stir::ROITests::run_tests(), and scale().

◆ get_geometric_volume()

float stir::Shape3D::get_geometric_volume ( ) const

virtual

Compute approximate volume.

As this is not possible/easy for all shapes, the default implementation returns a negative number. The user should check this to see if the returned value makes sense.

Reimplemented in stir::Box3D, stir::Ellipsoid, and stir::EllipsoidalCylinder.

References get_geometric_volume().

Referenced by get_geometric_volume(), and scale().