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)
virtual libMesh::Real	sample (const libMesh::Point &p) const
	Return the pixel value for the given point.
virtual void	setupImageSampler (MooseMesh &mesh)
	Perform initialization of image data.
std::string	fileSuffix ()
const std::vector< std::string > &	filenames ()

Static Public Member Functions
static InputParameters	validParams ()
	Constructor.

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

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

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

Detailed Description

A helper class for reading and sampling images using VTK.

Definition at line 83 of file ImageSampler.h.

Constructor & Destructor Documentation

ImageSampler()

ImageSampler::ImageSampler

(

const InputParameters &

parameters

)

Definition at line 58 of file ImageSampler.C.

  : FileRangeBuilder(parameters),
#ifdef LIBMESH_HAVE_VTK
    _data(nullptr),
    _algorithm(nullptr),
#endif
    _is_pars(parameters),
    _is_console((parameters.getCheckedPointerParam<MooseApp *>(MooseBase::app_param))
                    ->getOutputWarehouse()),
    _flip({{_is_pars.get<bool>("flip_x"),
            _is_pars.get<bool>("flip_y"),
            _is_pars.get<bool>("flip_z")}})
 
{
#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.

{
  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!");
  }
}

Referenced by ImageMesh::ImageMesh().

filenames()

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

inlineinherited

Definition at line 43 of file FileRangeBuilder.h.

{ return _filenames; }

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

fileSuffix()

std::string FileRangeBuilder::fileSuffix ( )

inlineinherited

Definition at line 42 of file FileRangeBuilder.h.

{ return _file_suffix; }

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

sample()

Real ImageSampler::sample ( const libMesh::Point &  p ) const

virtual

Return the pixel value for the given point.

Parameters

p	The point at which to extract pixel data

Definition at line 218 of file ImageSampler.C.

{
#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] = 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]--;
 
      // flip
      if (_flip[i])
        x[i] = _dims[i] - x[i] - 1;
    }
  }
 
  // 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
}

Referenced by ImageFunction::value().

setupImageSampler()

void ImageSampler::setupImageSampler ( MooseMesh &  mesh )

virtual

Perform initialization of image data.

Definition at line 80 of file ImageSampler.C.

{
  // 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();
#endif
}

Referenced by ImageFunction::initialSetup().

validParams()

InputParameters ImageSampler::validParams ( )

static

Constructor.

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

See also

ImageFunction

Definition at line 20 of file ImageSampler.C.

{
  // Define the general parameters
  InputParameters params = emptyInputParameters();
  params += FileRangeBuilder::validParams();
 
  params.addParam<Point>("origin", "Origin of the image (defaults to mesh origin)");
  params.addParam<Point>("dimensions",
                         "x,y,z dimensions of the image (defaults to mesh dimensions)");
  params.addParam<unsigned int>(
      "component",
      "The image RGB-component to return, leaving this blank will result in a greyscale value "
      "for the image to be created. The component number is zero based, i.e. 0 returns the first "
      "(RED) component of the image.");
 
  // Shift and Scale (application of these occurs prior to threshold)
  params.addParam<double>("shift", 0, "Value to add to all pixels; occurs prior to scaling");
  params.addParam<double>(
      "scale", 1, "Multiplier to apply to all pixel values; occurs after shifting");
  params.addParamNamesToGroup("shift scale", "Rescale");
 
  // Threshold parameters
  params.addParam<double>("threshold", "The threshold value");
  params.addParam<double>(
      "upper_value", 1, "The value to set for data greater than the threshold value");
  params.addParam<double>(
      "lower_value", 0, "The value to set for data less than the threshold value");
  params.addParamNamesToGroup("threshold upper_value lower_value", "Threshold");
 
  // Flip image
  params.addParam<bool>("flip_x", false, "Flip the image along the x-axis");
  params.addParam<bool>("flip_y", false, "Flip the image along the y-axis");
  params.addParam<bool>("flip_z", false, "Flip the image along the z-axis");
  params.addParamNamesToGroup("flip_x flip_y flip_z", "Flip");
 
  return params;
}

Referenced by ImageFunction::validParams().

vtkMagnitude()

void ImageSampler::vtkMagnitude ( )

protected

Convert the image to greyscale.

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

Definition at line 255 of file ImageSampler.C.

{
#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
}

Referenced by setupImageSampler().

vtkShiftAndScale()

void ImageSampler::vtkShiftAndScale ( )

protected

Apply image re-scaling using the vtkImageShiftAndRescale object.

Definition at line 274 of file ImageSampler.C.

{
#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
}

Referenced by setupImageSampler().

vtkThreshold()

void ImageSampler::vtkThreshold ( )

protected

Perform thresholding.

Definition at line 301 of file ImageSampler.C.

{
#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<vtkImageBinaryThreshold>::New();
 
  // Set the data source
  _image_threshold->SetInputConnection(_algorithm);
 
  // Setup the thresholding options
  _image_threshold->SetLowerThreshold(_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
}

Referenced by setupImageSampler().

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 137 of file ImageSampler.h.

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

_bounding_box

libMesh::BoundingBox ImageSampler::_bounding_box

private

Bounding box for testing points.

Definition at line 170 of file ImageSampler.h.

Referenced by sample(), and setupImageSampler().

_component

unsigned int ImageSampler::_component

private

Component to extract.

Definition at line 166 of file ImageSampler.h.

Referenced by sample(), and setupImageSampler().

_data

vtkImageData* ImageSampler::_data

private

Complete image data.

Definition at line 134 of file ImageSampler.h.

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

_dims

std::vector<int> ImageSampler::_dims

private

Pixel dimension of image.

Definition at line 156 of file ImageSampler.h.

Referenced by sample(), and setupImageSampler().

_file_suffix

std::string FileRangeBuilder::_file_suffix

protectedinherited

Definition at line 50 of file FileRangeBuilder.h.

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

_filenames

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

protectedinherited

Definition at line 51 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 131 of file ImageSampler.h.

Referenced by setupImageSampler().

_flip

std::array<bool, 3> ImageSampler::_flip

private

image flip

Definition at line 179 of file ImageSampler.h.

Referenced by sample().

_image

vtkSmartPointer<vtkImageReader2> ImageSampler::_image

private

Complete image data.

Definition at line 140 of file ImageSampler.h.

Referenced by setupImageSampler().

_image_threshold

vtkSmartPointer<vtkImageBinaryThreshold> ImageSampler::_image_threshold

private

Pointer to thresholding filter.

Definition at line 143 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 176 of file ImageSampler.h.

Referenced by setupImageSampler().

_is_pars

const InputParameters& ImageSampler::_is_pars

private

Parameters for interface.

Definition at line 173 of file ImageSampler.h.

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

_magnitude_filter

vtkSmartPointer<vtkImageMagnitude> ImageSampler::_magnitude_filter

private

Pointer to the magnitude filter.

Definition at line 149 of file ImageSampler.h.

Referenced by vtkMagnitude().

_origin

libMesh::Point ImageSampler::_origin

private

Origin of image.

Definition at line 153 of file ImageSampler.h.

Referenced by sample(), and setupImageSampler().

_physical_dims

libMesh::Point ImageSampler::_physical_dims

private

Physical dimensions of image.

Definition at line 159 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 146 of file ImageSampler.h.

Referenced by vtkShiftAndScale().

_status

int FileRangeBuilder::_status

protectedinherited

Definition at line 49 of file FileRangeBuilder.h.

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

_voxel

std::vector<double> ImageSampler::_voxel

private

Physical pixel size.

Definition at line 162 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