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. More...
virtual void	setupImageSampler (MooseMesh &mesh)
	Perform initialization of image data. More...
std::string	fileSuffix ()
const std::vector< std::string > &	filenames ()

Static Public Member Functions
static InputParameters	validParams ()
	Constructor. More...

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	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. 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...
libMesh::Point	_origin
	Origin of image. More...
std::vector< int >	_dims
	Pixel dimension of image. More...
libMesh::Point	_physical_dims
	Physical dimensions of image. More...
std::vector< double >	_voxel
	Physical pixel size. More...
unsigned int	_component
	Component to extract. More...
libMesh::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...
std::array< bool, 3 >	_flip
	image flip More...

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 *>("_moose_app"))->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.

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 43 of file FileRangeBuilder.h.

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

{ return _filenames; }

fileSuffix()

std::string FileRangeBuilder::fileSuffix ( )

inlineinherited

Definition at line 42 of file FileRangeBuilder.h.

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

{ return _file_suffix; }

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.

Referenced by 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] = 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
}

setupImageSampler()

void ImageSampler::setupImageSampler ( MooseMesh &  mesh )

virtual

Perform initialization of image data.

Definition at line 80 of file ImageSampler.C.

Referenced by ImageFunction::initialSetup().

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

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.

Referenced by ImageFunction::validParams().

{
  // 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;
}

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.

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 274 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 301 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 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<vtkImageThreshold> 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