ImageSampler Class Reference

A helper class for reading and sampling images using VTK. More...

#include <ImageSampler.h>

Inheritance diagram for ImageSampler:

Public Member Functions
	ImageSampler (const InputParameters &parameters)
	Constructor. More...
virtual Real	sample (const Point &p)
	Return the pixel value for the given point. More...
virtual void	setupImageSampler (MooseMesh &mesh)
	Perform initialization of image data. More...
std::string	fileSuffix ()
const std::vector< std::string > &	filenames ()

Protected Member Functions
void	vtkShiftAndScale ()
	Apply image re-scaling using the vtkImageShiftAndRescale object. More...
void	vtkThreshold ()
	Perform thresholding. More...
void	vtkMagnitude ()
	Convert the image to greyscale. More...
void	vtkFlip ()
	Perform image flipping. More...
void	errorCheck ()

Protected Attributes
int	_status
std::string	_file_suffix
std::vector< std::string >	_filenames

Private Member Functions
vtkSmartPointer< vtkImageFlip >	imageFlip (const int &axis)
	Helper method for flipping image. More...

Private Attributes
vtkSmartPointer< vtkStringArray >	_files
	List of file names to extract data. More...
vtkImageData *	_data
	Complete image data. More...
vtkAlgorithmOutput *	_algorithm
	VTK-6 seems to work better in terms of "algorithm outputs" rather than vtkImageData pointers... More...
vtkSmartPointer< vtkImageReader2 >	_image
	Complete image data. More...
vtkSmartPointer< vtkImageThreshold >	_image_threshold
	Pointer to thresholding filter. More...
vtkSmartPointer< vtkImageShiftScale >	_shift_scale_filter
	Pointer to the shift and scaling filter. More...
vtkSmartPointer< vtkImageMagnitude >	_magnitude_filter
	Pointer to the magnitude filter. More...
vtkSmartPointer< vtkImageFlip >	_flip_filter
	Pointers to image flipping filter. May be used for x, y, or z. More...
Point	_origin
	Origin of image. More...
std::vector< int >	_dims
	Pixel dimension of image. More...
Point	_physical_dims
	Physical dimensions of image. More...
std::vector< double >	_voxel
	Physical pixel size. More...
unsigned int	_component
	Component to extract. More...
BoundingBox	_bounding_box
	Bounding box for testing points. More...
const InputParameters &	_is_pars
	Parameters for interface. More...
ConsoleStream	_is_console
	Create a console stream object for this helper class. More...

Detailed Description

A helper class for reading and sampling images using VTK.

Definition at line 52 of file ImageSampler.h.

Constructor & Destructor Documentation

ImageSampler()

ImageSampler::ImageSampler

(

const InputParameters &

parameters

)

Constructor.

Use this object as an interface, being sure to also add the parameters to the child class.

See also

ImageFunction

Definition at line 57 of file ImageSampler.C.

  : FileRangeBuilder(parameters),
#ifdef LIBMESH_HAVE_VTK
    _data(NULL),
    _algorithm(NULL),
#endif
    _is_pars(parameters),
    _is_console((parameters.getCheckedPointerParam<MooseApp *>("_moose_app"))->getOutputWarehouse())

{
#ifndef LIBMESH_HAVE_VTK
  // This should be impossible to reach, the registration of ImageSampler is also guarded with
  // LIBMESH_HAVE_VTK
  mooseError("libMesh must be configured with VTK enabled to utilize ImageSampler");
#endif
}

Member Function Documentation

errorCheck()

void FileRangeBuilder::errorCheck ( )

protectedinherited

Definition at line 159 of file FileRangeBuilder.C.

Referenced by ImageMesh::ImageMesh().

{
  switch (_status)
  {
    case 0:
      return;
    case 1:
      mooseError("Cannot provide both file and file_base parameters");
      break;
    case 2:
      mooseError("You must provide a valid value for either the 'file' parameter or the "
                 "'file_base' parameter.");
      break;
    case 3:
      mooseError(
          "If you provide a 'file_base', you must also provide a valid 'file_suffix', e.g. 'png'.");
      break;
    default:
      mooseError("Unknown error code!");
  }
}

filenames()

const std::vector<std::string>& FileRangeBuilder::filenames ( )

inlineinherited

Definition at line 46 of file FileRangeBuilder.h.

Referenced by ImageMeshGenerator::buildMesh3D(), ImageMesh::buildMesh3D(), setupImageSampler(), and MeshBaseImageSampler::setupImageSampler().

{ return _filenames; }

fileSuffix()

std::string FileRangeBuilder::fileSuffix ( )

inlineinherited

Definition at line 45 of file FileRangeBuilder.h.

Referenced by setupImageSampler(), and MeshBaseImageSampler::setupImageSampler().

{ return _file_suffix; }

imageFlip()

vtkSmartPointer< vtkImageFlip > ImageSampler::imageFlip ( const int &  axis )

private

Helper method for flipping image.

Parameters

axis	Flag for determing the flip axis: "x=0", "y=1", "z=2"

Returns

A smart pointer the flipping filter

Definition at line 355 of file ImageSampler.C.

Referenced by vtkFlip().

{
  vtkSmartPointer<vtkImageFlip> flip_image = vtkSmartPointer<vtkImageFlip>::New();

  flip_image->SetFilteredAxis(axis);

  // Set the data source
  flip_image->SetInputConnection(_algorithm);

  // Perform the flip
  flip_image->Update();

  // Return the flip filter pointer
  return flip_image;
}

sample()

Real ImageSampler::sample ( const Point &  p )

virtual

Return the pixel value for the given point.

Parameters

p	The point at which to extract pixel data

Definition at line 214 of file ImageSampler.C.

Referenced by ImageSubdomain::modify(), and ImageFunction::value().

{
#ifdef LIBMESH_HAVE_VTK

  // Do nothing if the point is outside of the image domain
  if (!_bounding_box.contains_point(p))
    return 0.0;

  // Determine pixel coordinates
  std::vector<int> x(3, 0);
  for (int i = 0; i < LIBMESH_DIM; ++i)
  {
    // Compute position, only if voxel size is greater than zero
    if (_voxel[i] == 0)
      x[i] = 0;

    else
    {
      x[i] = std::floor((p(i) - _origin(i)) / _voxel[i]);

      // If the point falls on the mesh extents the index needs to be decreased by one
      if (x[i] == _dims[i])
        x[i]--;
    }
  }

  // Return the image data at the given point
  return _data->GetScalarComponentAsDouble(x[0], x[1], x[2], _component);

#else
  libmesh_ignore(p); // avoid un-used parameter warnings
  return 0.0;
#endif
}

setupImageSampler()

void ImageSampler::setupImageSampler ( MooseMesh &  mesh )

virtual

Perform initialization of image data.

Definition at line 75 of file ImageSampler.C.

Referenced by ImageFunction::initialSetup(), and ImageSubdomain::modify().

{
  // Don't warn that mesh or _is_pars are unused when VTK is not enabled.
  libmesh_ignore(mesh);
  libmesh_ignore(_is_pars);

#ifdef LIBMESH_HAVE_VTK
  // Get access to the Mesh object
  BoundingBox bbox = MeshTools::create_bounding_box(mesh.getMesh());

  // Set the dimensions from the Mesh if not set by the User
  if (_is_pars.isParamValid("dimensions"))
    _physical_dims = _is_pars.get<Point>("dimensions");

  else
  {
    _physical_dims(0) = bbox.max()(0) - bbox.min()(0);
#if LIBMESH_DIM > 1
    _physical_dims(1) = bbox.max()(1) - bbox.min()(1);
#endif
#if LIBMESH_DIM > 2
    _physical_dims(2) = bbox.max()(2) - bbox.min()(2);
#endif
  }

  // Set the origin from the Mesh if not set in the input file
  if (_is_pars.isParamValid("origin"))
    _origin = _is_pars.get<Point>("origin");
  else
  {
    _origin(0) = bbox.min()(0);
#if LIBMESH_DIM > 1
    _origin(1) = bbox.min()(1);
#endif
#if LIBMESH_DIM > 2
    _origin(2) = bbox.min()(2);
#endif
  }

  // An array of filenames, to be filled in
  std::vector<std::string> filenames;

  // The file suffix, to be determined
  std::string file_suffix;

  // Try to parse our own file range parameters.  If that fails, then
  // see if the associated Mesh is an ImageMesh and use its.  If that
  // also fails, then we have to throw an error...
  //
  // The parseFileRange method sets parameters, thus a writable reference to the InputParameters
  // object must be obtained from the warehouse. Generally, this should be avoided, but
  // this is a special case.
  if (_status != 0)
  {
    // We don't have parameters, so see if we can get them from ImageMesh
    ImageMesh * image_mesh = dynamic_cast<ImageMesh *>(&mesh);
    if (!image_mesh)
      mooseError("No file range parameters were provided and the Mesh is not an ImageMesh.");

    // Get the ImageMesh's parameters.  This should work, otherwise
    // errors would already have been thrown...
    filenames = image_mesh->filenames();
    file_suffix = image_mesh->fileSuffix();
  }
  else
  {
    // Use our own parameters (using 'this' b/c of conflicts with filenames the local variable)
    filenames = this->filenames();
    file_suffix = fileSuffix();
  }

  // Storage for the file names
  _files = vtkSmartPointer<vtkStringArray>::New();

  for (const auto & filename : filenames)
    _files->InsertNextValue(filename);

  // Error if no files where located
  if (_files->GetNumberOfValues() == 0)
    mooseError("No image file(s) located");

  // Read the image stack.  Hurray for VTK not using polymorphism in a
  // smart way... we actually have to explicitly create the type of
  // reader based on the file extension, using an if-statement...
  if (file_suffix == "png")
    _image = vtkSmartPointer<vtkPNGReader>::New();
  else if (file_suffix == "tiff" || file_suffix == "tif")
    _image = vtkSmartPointer<vtkTIFFReader>::New();
  else
    mooseError("Un-supported file type '", file_suffix, "'");

  // Now that _image is set up, actually read the images
  // Indicate that data read has started
  _is_console << "Reading image(s)..." << std::endl;

  // Extract the data
  _image->SetFileNames(_files);
  _image->Update();
  _data = _image->GetOutput();
  _algorithm = _image->GetOutputPort();

  // Set the image dimensions and voxel size member variable
  int * dims = _data->GetDimensions();
  for (unsigned int i = 0; i < 3; ++i)
  {
    _dims.push_back(dims[i]);
    _voxel.push_back(_physical_dims(i) / _dims[i]);
  }

  // Set the dimensions of the image and bounding box
  _data->SetSpacing(_voxel[0], _voxel[1], _voxel[2]);
  _data->SetOrigin(_origin(0), _origin(1), _origin(2));
  _bounding_box.min() = _origin;
  _bounding_box.max() = _origin + _physical_dims;

  // Indicate data read is completed
  _is_console << "          ...image read finished" << std::endl;

  // Set the component parameter
  // If the parameter is not set then vtkMagnitude() will applied
  if (_is_pars.isParamValid("component"))
  {
    unsigned int n = _data->GetNumberOfScalarComponents();
    _component = _is_pars.get<unsigned int>("component");
    if (_component >= n)
      mooseError("'component' parameter must be empty or have a value of 0 to ", n - 1);
  }
  else
    _component = 0;

  // Apply filters, the toggling on and off of each filter is handled internally
  vtkMagnitude();
  vtkShiftAndScale();
  vtkThreshold();
  vtkFlip();
#endif
}

vtkFlip()

void ImageSampler::vtkFlip ( )

protected

Perform image flipping.

Flip the image along the x, y, and/or z axis. If multiple flips occur, they happen in order.

Definition at line 332 of file ImageSampler.C.

Referenced by setupImageSampler().

{
#ifdef LIBMESH_HAVE_VTK
  // Convert boolean values into an integer array, then loop over it
  int mask[3] = {
      _is_pars.get<bool>("flip_x"), _is_pars.get<bool>("flip_y"), _is_pars.get<bool>("flip_z")};

  for (int dim = 0; dim < 3; ++dim)
  {
    if (mask[dim])
    {
      _flip_filter = imageFlip(dim);

      // Update pointers
      _data = _flip_filter->GetOutput();
      _algorithm = _flip_filter->GetOutputPort();
    }
  }
#endif
}

vtkMagnitude()

void ImageSampler::vtkMagnitude ( )

protected

Convert the image to greyscale.

By leaving the 'component' input parameter empty, this is called automatically.

Definition at line 250 of file ImageSampler.C.

Referenced by setupImageSampler().

{
#ifdef LIBMESH_HAVE_VTK
  // Do nothing if 'component' is set
  if (_is_pars.isParamValid("component"))
    return;

  // Apply the greyscale filtering
  _magnitude_filter = vtkSmartPointer<vtkImageMagnitude>::New();
  _magnitude_filter->SetInputConnection(_algorithm);
  _magnitude_filter->Update();

  // Update the pointers
  _data = _magnitude_filter->GetOutput();
  _algorithm = _magnitude_filter->GetOutputPort();
#endif
}

vtkShiftAndScale()

void ImageSampler::vtkShiftAndScale ( )

protected

Apply image re-scaling using the vtkImageShiftAndRescale object.

Definition at line 269 of file ImageSampler.C.

Referenced by setupImageSampler().

{
#ifdef LIBMESH_HAVE_VTK
  // Capture the parameters
  double shift = _is_pars.get<double>("shift");
  double scale = _is_pars.get<double>("scale");

  // Do nothing if shift and scale are not set
  if (shift == 0 && scale == 1)
    return;

  // Perform the scaling and offset actions
  _shift_scale_filter = vtkSmartPointer<vtkImageShiftScale>::New();
  _shift_scale_filter->SetOutputScalarTypeToDouble();

  _shift_scale_filter->SetInputConnection(_algorithm);
  _shift_scale_filter->SetShift(shift);
  _shift_scale_filter->SetScale(scale);
  _shift_scale_filter->Update();

  // Update the pointers
  _data = _shift_scale_filter->GetOutput();
  _algorithm = _shift_scale_filter->GetOutputPort();
#endif
}

vtkThreshold()

void ImageSampler::vtkThreshold ( )

protected

Perform thresholding.

Definition at line 296 of file ImageSampler.C.

Referenced by setupImageSampler().

{
#ifdef LIBMESH_HAVE_VTK
  // Do nothing if threshold not set
  if (!_is_pars.isParamValid("threshold"))
    return;

  // Error if both upper and lower are not set
  if (!_is_pars.isParamValid("upper_value") || !_is_pars.isParamValid("lower_value"))
    mooseError("When thresholding is applied, both the upper_value and lower_value parameters must "
               "be set");

  // Create the thresholding object
  _image_threshold = vtkSmartPointer<vtkImageThreshold>::New();

  // Set the data source
  _image_threshold->SetInputConnection(_algorithm);

  // Setup the thresholding options
  _image_threshold->ThresholdByUpper(_is_pars.get<Real>("threshold"));
  _image_threshold->ReplaceInOn();
  _image_threshold->SetInValue(_is_pars.get<Real>("upper_value"));
  _image_threshold->ReplaceOutOn();
  _image_threshold->SetOutValue(_is_pars.get<Real>("lower_value"));
  _image_threshold->SetOutputScalarTypeToDouble();

  // Perform the thresholding
  _image_threshold->Update();

  // Update the pointers
  _data = _image_threshold->GetOutput();
  _algorithm = _image_threshold->GetOutputPort();
#endif
}

Member Data Documentation

_algorithm

vtkAlgorithmOutput* ImageSampler::_algorithm

private

VTK-6 seems to work better in terms of "algorithm outputs" rather than vtkImageData pointers...

Definition at line 111 of file ImageSampler.h.

Referenced by imageFlip(), setupImageSampler(), vtkFlip(), vtkMagnitude(), vtkShiftAndScale(), and vtkThreshold().

_bounding_box

BoundingBox ImageSampler::_bounding_box

private

Bounding box for testing points.

Definition at line 156 of file ImageSampler.h.

Referenced by sample(), and setupImageSampler().

_component

unsigned int ImageSampler::_component

private

Component to extract.

Definition at line 152 of file ImageSampler.h.

Referenced by sample(), and setupImageSampler().

_data

vtkImageData* ImageSampler::_data

private

Complete image data.

Definition at line 108 of file ImageSampler.h.

Referenced by sample(), setupImageSampler(), vtkFlip(), vtkMagnitude(), vtkShiftAndScale(), and vtkThreshold().

_dims

std::vector<int> ImageSampler::_dims

private

Pixel dimension of image.

Definition at line 142 of file ImageSampler.h.

Referenced by sample(), and setupImageSampler().

_file_suffix

std::string FileRangeBuilder::_file_suffix

protectedinherited

Definition at line 53 of file FileRangeBuilder.h.

Referenced by FileRangeBuilder::FileRangeBuilder(), and FileRangeBuilder::fileSuffix().

_filenames

std::vector<std::string> FileRangeBuilder::_filenames

protectedinherited

Definition at line 54 of file FileRangeBuilder.h.

Referenced by ImageMesh::buildMesh(), FileRangeBuilder::filenames(), FileRangeBuilder::FileRangeBuilder(), and ImageMeshGenerator::generate().

_files

vtkSmartPointer<vtkStringArray> ImageSampler::_files

private

List of file names to extract data.

Definition at line 105 of file ImageSampler.h.

Referenced by setupImageSampler().

_flip_filter

vtkSmartPointer<vtkImageFlip> ImageSampler::_flip_filter

private

Pointers to image flipping filter. May be used for x, y, or z.

Definition at line 126 of file ImageSampler.h.

Referenced by vtkFlip().

_image

vtkSmartPointer<vtkImageReader2> ImageSampler::_image

private

Complete image data.

Definition at line 114 of file ImageSampler.h.

Referenced by setupImageSampler().

_image_threshold

vtkSmartPointer<vtkImageThreshold> ImageSampler::_image_threshold

private

Pointer to thresholding filter.

Definition at line 117 of file ImageSampler.h.

Referenced by vtkThreshold().

_is_console

ConsoleStream ImageSampler::_is_console

private

Create a console stream object for this helper class.

Definition at line 162 of file ImageSampler.h.

Referenced by setupImageSampler().

_is_pars

const InputParameters& ImageSampler::_is_pars

private

Parameters for interface.

Definition at line 159 of file ImageSampler.h.

Referenced by setupImageSampler(), vtkFlip(), vtkMagnitude(), vtkShiftAndScale(), and vtkThreshold().

_magnitude_filter

vtkSmartPointer<vtkImageMagnitude> ImageSampler::_magnitude_filter

private

Pointer to the magnitude filter.

Definition at line 123 of file ImageSampler.h.

Referenced by vtkMagnitude().

_origin

Point ImageSampler::_origin

private

Origin of image.

Definition at line 139 of file ImageSampler.h.

Referenced by sample(), and setupImageSampler().

_physical_dims

Point ImageSampler::_physical_dims

private

Physical dimensions of image.

Definition at line 145 of file ImageSampler.h.

Referenced by setupImageSampler().

_shift_scale_filter

vtkSmartPointer<vtkImageShiftScale> ImageSampler::_shift_scale_filter

private

Pointer to the shift and scaling filter.

Definition at line 120 of file ImageSampler.h.

Referenced by vtkShiftAndScale().

_status

int FileRangeBuilder::_status

protectedinherited

Definition at line 52 of file FileRangeBuilder.h.

Referenced by FileRangeBuilder::errorCheck(), FileRangeBuilder::FileRangeBuilder(), setupImageSampler(), and MeshBaseImageSampler::setupImageSampler().

_voxel

std::vector<double> ImageSampler::_voxel

private

Physical pixel size.

Definition at line 148 of file ImageSampler.h.

Referenced by sample(), and setupImageSampler().

---

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

• include/utils/ImageSampler.h
• src/utils/ImageSampler.C