ImageMesh

Generated mesh with the aspect ratio of a given image stack.

Description

The ImageMesh object is a convenience tool for setting up a mesh to match the pixel structure of a two or three dimensional image. It is generally used in union with the ImageFunction object to perform simulations that rely on image data, such as setting up an initial condition of a grain structure. By default the generated mesh is sized to the dimensions of the images and creates one element per pixel.

Example Syntax

[Mesh]
  type = ImageMesh
  dim = 3
  file_base = stack/test
  file_suffix = png
[]

Input Parameters

dimThe dimension of the mesh to be generated
C++ Type:MooseEnum
Options:1, 2, 3
Controllable:No
Description:The dimension of the mesh to be generated

Required Parameters

add_subdomain_idsThe listed subdomains will be assumed valid for the mesh. This permits setting up subdomain restrictions for subdomains initially containing no elements, which can occur, for example, in additive manufacturing simulations which dynamically add and remove elements.
C++ Type:std::vector<unsigned short>
Controllable:No
Description:The listed subdomains will be assumed valid for the mesh. This permits setting up subdomain restrictions for subdomains initially containing no elements, which can occur, for example, in additive manufacturing simulations which dynamically add and remove elements.
allow_renumberingTrueIf allow_renumbering=false, node and element numbers are kept fixed until deletion
Default:True
C++ Type:bool
Controllable:No
Description:If allow_renumbering=false, node and element numbers are kept fixed until deletion
bias_x1The amount by which to grow (or shrink) the cells in the x-direction.
Default:1
C++ Type:double
Controllable:No
Description:The amount by which to grow (or shrink) the cells in the x-direction.
bias_y1The amount by which to grow (or shrink) the cells in the y-direction.
Default:1
C++ Type:double
Controllable:No
Description:The amount by which to grow (or shrink) the cells in the y-direction.
bias_z1The amount by which to grow (or shrink) the cells in the z-direction.
Default:1
C++ Type:double
Controllable:No
Description:The amount by which to grow (or shrink) the cells in the z-direction.
build_all_side_lowerd_meshFalseTrue to build the lower-dimensional mesh for all sides.
Default:False
C++ Type:bool
Controllable:No
Description:True to build the lower-dimensional mesh for all sides.
cells_per_pixel1The number of mesh cells per pixel, must be <=1
Default:1
C++ Type:double
Controllable:No
Description:The number of mesh cells per pixel, must be <=1
coord_blockBlock IDs for the coordinate systems. If this parameter is specified, then it must encompass all the subdomains on the mesh.
C++ Type:std::vector<SubdomainName>
Controllable:No
Description:Block IDs for the coordinate systems. If this parameter is specified, then it must encompass all the subdomains on the mesh.
elem_typeThe type of element from libMesh to generate (default: linear element for requested dimension)
C++ Type:MooseEnum
Options:EDGE, EDGE2, EDGE3, EDGE4, QUAD, QUAD4, QUAD8, QUAD9, TRI, TRI3, TRI6, TRI7, HEX, HEX8, HEX20, HEX27, TET, TET4, TET10, TET14, PRISM, PRISM6, PRISM15, PRISM18, PYRAMID, PYRAMID5, PYRAMID13, PYRAMID14
Controllable:No
Description:The type of element from libMesh to generate (default: linear element for requested dimension)
fileName of single image file to extract mesh parameters from. If provided, a 2D mesh is created.
C++ Type:FileName
Controllable:No
Description:Name of single image file to extract mesh parameters from. If provided, a 2D mesh is created.
file_baseImage file base to open, use this option when a stack of images must be read (ignored if 'file' is given)
C++ Type:FileNameNoExtension
Controllable:No
Description:Image file base to open, use this option when a stack of images must be read (ignored if 'file' is given)
file_rangeRange of images to analyze, used with 'file_base' (ignored if 'file' is given)
C++ Type:std::vector<unsigned int>
Controllable:No
Description:Range of images to analyze, used with 'file_base' (ignored if 'file' is given)
file_suffixSuffix of the file to open, e.g. 'png'
C++ Type:std::string
Controllable:No
Description:Suffix of the file to open, e.g. 'png'
gauss_lobatto_gridFalseGrade mesh into boundaries according to Gauss-Lobatto quadrature spacing.
Default:False
C++ Type:bool
Controllable:No
Description:Grade mesh into boundaries according to Gauss-Lobatto quadrature spacing.
ghosting_patch_sizeThe number of nearest neighbors considered for ghosting purposes when 'iteration' patch update strategy is used. Default is 5 * patch_size.
C++ Type:unsigned int
Controllable:No
Description:The number of nearest neighbors considered for ghosting purposes when 'iteration' patch update strategy is used. Default is 5 * patch_size.
max_leaf_size10The maximum number of points in each leaf of the KDTree used in the nearest neighbor search. As the leaf size becomes larger,KDTree construction becomes faster but the nearest neighbor searchbecomes slower.
Default:10
C++ Type:unsigned int
Controllable:No
Description:The maximum number of points in each leaf of the KDTree used in the nearest neighbor search. As the leaf size becomes larger,KDTree construction becomes faster but the nearest neighbor searchbecomes slower.
nx1Number of elements in the X direction
Default:1
C++ Type:unsigned int
Controllable:No
Description:Number of elements in the X direction
ny1Number of elements in the Y direction
Default:1
C++ Type:unsigned int
Controllable:No
Description:Number of elements in the Y direction
nz1Number of elements in the Z direction
Default:1
C++ Type:unsigned int
Controllable:No
Description:Number of elements in the Z direction
parallel_typeDEFAULTDEFAULT: Use libMesh::ReplicatedMesh unless --distributed-mesh is specified on the command line REPLICATED: Always use libMesh::ReplicatedMesh DISTRIBUTED: Always use libMesh::DistributedMesh
Default:DEFAULT
C++ Type:MooseEnum
Options:DEFAULT, REPLICATED, DISTRIBUTED
Controllable:No
Description:DEFAULT: Use libMesh::ReplicatedMesh unless --distributed-mesh is specified on the command line REPLICATED: Always use libMesh::ReplicatedMesh DISTRIBUTED: Always use libMesh::DistributedMesh
scale_to_oneTrueWhether or not to scale the image so its max dimension is 1
Default:True
C++ Type:bool
Controllable:No
Description:Whether or not to scale the image so its max dimension is 1
skip_refine_when_use_splitTrueTrue to skip uniform refinements when using a pre-split mesh.
Default:True
C++ Type:bool
Controllable:No
Description:True to skip uniform refinements when using a pre-split mesh.
xmax1Upper X Coordinate of the generated mesh
Default:1
C++ Type:double
Controllable:No
Description:Upper X Coordinate of the generated mesh
xmin0Lower X Coordinate of the generated mesh
Default:0
C++ Type:double
Controllable:No
Description:Lower X Coordinate of the generated mesh
ymax1Upper Y Coordinate of the generated mesh
Default:1
C++ Type:double
Controllable:No
Description:Upper Y Coordinate of the generated mesh
ymin0Lower Y Coordinate of the generated mesh
Default:0
C++ Type:double
Controllable:No
Description:Lower Y Coordinate of the generated mesh
zmax1Upper Z Coordinate of the generated mesh
Default:1
C++ Type:double
Controllable:No
Description:Upper Z Coordinate of the generated mesh
zmin0Lower Z Coordinate of the generated mesh
Default:0
C++ Type:double
Controllable:No
Description:Lower Z Coordinate of the generated mesh

Optional Parameters

alpha_rotationThe number of degrees that the domain should be alpha-rotated using the Euler angle ZXZ convention from https://en.wikipedia.org/wiki/Euler_angles#Rotation_matrix in order to align with a canonical physical space of your choosing.
C++ Type:double
Controllable:No
Description:The number of degrees that the domain should be alpha-rotated using the Euler angle ZXZ convention from https://en.wikipedia.org/wiki/Euler_angles#Rotation_matrix in order to align with a canonical physical space of your choosing.
beta_rotationThe number of degrees that the domain should be beta-rotated using the Euler angle ZXZ convention from https://en.wikipedia.org/wiki/Euler_angles#Rotation_matrix in order to align with a canonical physical space of your choosing.
C++ Type:double
Controllable:No
Description:The number of degrees that the domain should be beta-rotated using the Euler angle ZXZ convention from https://en.wikipedia.org/wiki/Euler_angles#Rotation_matrix in order to align with a canonical physical space of your choosing.
gamma_rotationThe number of degrees that the domain should be gamma-rotated using the Euler angle ZXZ convention from https://en.wikipedia.org/wiki/Euler_angles#Rotation_matrix in order to align with a canonical physical space of your choosing.
C++ Type:double
Controllable:No
Description:The number of degrees that the domain should be gamma-rotated using the Euler angle ZXZ convention from https://en.wikipedia.org/wiki/Euler_angles#Rotation_matrix in order to align with a canonical physical space of your choosing.
length_unitHow much distance one mesh length unit represents, e.g. 1 cm, 1 nm, 1 ft, 5inches
C++ Type:std::string
Controllable:No
Description:How much distance one mesh length unit represents, e.g. 1 cm, 1 nm, 1 ft, 5inches
up_directionSpecify what axis corresponds to the up direction in physical space (the opposite of the gravity vector if you will). If this parameter is provided, we will perform a single 90 degree rotation of the domain--if the provided axis is 'x' or 'z', we will not rotate if the axis is 'y'--such that a point which was on the provided axis will now lie on the y-axis, e.g. the y-axis is our canonical up direction. If you want finer grained control than this, please use the 'alpha_rotation', 'beta_rotation', and 'gamma_rotation' parameters.
C++ Type:MooseEnum
Options:X, Y, Z
Controllable:No
Description:Specify what axis corresponds to the up direction in physical space (the opposite of the gravity vector if you will). If this parameter is provided, we will perform a single 90 degree rotation of the domain--if the provided axis is 'x' or 'z', we will not rotate if the axis is 'y'--such that a point which was on the provided axis will now lie on the y-axis, e.g. the y-axis is our canonical up direction. If you want finer grained control than this, please use the 'alpha_rotation', 'beta_rotation', and 'gamma_rotation' parameters.

Transformations Relative To Parent Application Frame Of Reference Parameters

coord_typeXYZType of the coordinate system per block param
Default:XYZ
C++ Type:MultiMooseEnum
Options:XYZ, RZ, RSPHERICAL
Controllable:No
Description:Type of the coordinate system per block param
rz_coord_axisYThe rotation axis (X | Y) for axisymmetric coordinates
Default:Y
C++ Type:MooseEnum
Options:X, Y
Controllable:No
Description:The rotation axis (X | Y) for axisymmetric coordinates
rz_coord_blocksBlocks using general axisymmetric coordinate systems
C++ Type:std::vector<SubdomainName>
Controllable:No
Description:Blocks using general axisymmetric coordinate systems
rz_coord_directionsAxis directions for each block in 'rz_coord_blocks'
C++ Type:std::vector<libMesh::VectorValue<double>>
Controllable:No
Description:Axis directions for each block in 'rz_coord_blocks'
rz_coord_originsAxis origin points for each block in 'rz_coord_blocks'
C++ Type:std::vector<libMesh::Point>
Controllable:No
Description:Axis origin points for each block in 'rz_coord_blocks'

Coordinate System Parameters

centroid_partitioner_directionSpecifies the sort direction if using the centroid partitioner. Available options: x, y, z, radial
C++ Type:MooseEnum
Options:x, y, z, radial
Controllable:No
Description:Specifies the sort direction if using the centroid partitioner. Available options: x, y, z, radial
partitionerdefaultSpecifies a mesh partitioner to use when splitting the mesh for a parallel computation.
Default:default
C++ Type:MooseEnum
Options:default, metis, parmetis, linear, centroid, hilbert_sfc, morton_sfc
Controllable:No
Description:Specifies a mesh partitioner to use when splitting the mesh for a parallel computation.

Partitioning Parameters

construct_node_list_from_side_listTrueWhether or not to generate nodesets from the sidesets (usually a good idea).
Default:True
C++ Type:bool
Controllable:No
Description:Whether or not to generate nodesets from the sidesets (usually a good idea).
control_tagsAdds user-defined labels for accessing object parameters via control logic.
C++ Type:std::vector<std::string>
Controllable:No
Description:Adds user-defined labels for accessing object parameters via control logic.
enableTrueSet the enabled status of the MooseObject.
Default:True
C++ Type:bool
Controllable:No
Description:Set the enabled status of the MooseObject.
nemesisFalseIf nemesis=true and file=foo.e, actually reads foo.e.N.0, foo.e.N.1, ... foo.e.N.N-1, where N = # CPUs, with NemesisIO.
Default:False
C++ Type:bool
Controllable:No
Description:If nemesis=true and file=foo.e, actually reads foo.e.N.0, foo.e.N.1, ... foo.e.N.N-1, where N = # CPUs, with NemesisIO.
patch_size40The number of nodes to consider in the NearestNode neighborhood.
Default:40
C++ Type:unsigned int
Controllable:No
Description:The number of nodes to consider in the NearestNode neighborhood.
patch_update_strategyneverHow often to update the geometric search 'patch'. The default is to never update it (which is the most efficient but could be a problem with lots of relative motion). 'always' will update the patch for all secondary nodes at the beginning of every timestep which might be time consuming. 'auto' will attempt to determine at the start of which timesteps the patch for all secondary nodes needs to be updated automatically.'iteration' updates the patch at every nonlinear iteration for a subset of secondary nodes for which penetration is not detected. If there can be substantial relative motion between the primary and secondary surfaces during the nonlinear iterations within a timestep, it is advisable to use 'iteration' option to ensure accurate contact detection.
Default:never
C++ Type:MooseEnum
Options:never, always, auto, iteration
Controllable:No
Description:How often to update the geometric search 'patch'. The default is to never update it (which is the most efficient but could be a problem with lots of relative motion). 'always' will update the patch for all secondary nodes at the beginning of every timestep which might be time consuming. 'auto' will attempt to determine at the start of which timesteps the patch for all secondary nodes needs to be updated automatically.'iteration' updates the patch at every nonlinear iteration for a subset of secondary nodes for which penetration is not detected. If there can be substantial relative motion between the primary and secondary surfaces during the nonlinear iterations within a timestep, it is advisable to use 'iteration' option to ensure accurate contact detection.

Advanced Parameters

Input Files

(test/tests/functions/image_function/moose_logo_test_2D.i)
(modules/phase_field/test/tests/feature_flood_test/parallel_feature_count.i)
(modules/phase_field/test/tests/boundary_intersecting_features/boundary_intersecting_features.i)
(test/tests/functions/image_function/image_mesh_3d.i)
(test/tests/functions/image_function/image_mesh_2d.i)

(test/tests/functions/image_function/image_mesh_3d.i)

[Mesh]
  type = ImageMesh
  dim = 3
  file_base = stack/test
  file_suffix = png
[]

[Variables]
  [u]
  []
[]

[Functions]
  [image_func]
    # ImageFunction gets its file range parameters from ImageMesh,
    # when it is present.  This prevents duplicating information in
    # input files.
    type = ImageFunction
  []
[]

[ICs]
  [u_ic]
    type = FunctionIC
    function = image_func
    variable = u
  []
[]

[Problem]
  type = FEProblem
  solve = false
[]

[Executioner]
  type = Transient
  num_steps = 1
  dt = 0.1
[]

[Outputs]
  exodus = true
[]

(test/tests/functions/image_function/moose_logo_test_2D.i)

[Problem]
  solve = false
[]

[Mesh]
  type = ImageMesh
  cells_per_pixel = 1
  dim = 2
  file = moose_logo_small.png
[]

[Variables]
  [original]
    family = MONOMIAL
    order = CONSTANT
  []
  [scaled]
    family = MONOMIAL
    order = CONSTANT
  []
  [shifted]
    family = MONOMIAL
    order = CONSTANT
  []
[]

[Functions]
  [image]
    type = ImageFunction
    file = moose_logo_small.png
  []
  [image_scale]
    type = ImageFunction
    file = moose_logo_small.png
    scale = 0.00392156862
  []
  [image_shift]
    type = ImageFunction
    file = moose_logo_small.png
    shift = -127.5
  []
[]

[ICs]
  [original_IC]
    type = FunctionIC
    function = image
    variable = original
  []
  [scaled_IC]
    type = FunctionIC
    function = image_scale
    variable = scaled
  []
  [shifted_IC]
    type = FunctionIC
    function = image_shift
    variable = shifted
  []
[]

[Executioner]
  type = Steady
[]

[Outputs]
  exodus = true
[]

(modules/phase_field/test/tests/feature_flood_test/parallel_feature_count.i)

[Mesh]
  type = ImageMesh
  dim = 2
  file = spiral_16x16.png
  scale_to_one = false
[]

[Variables]
  [./u]
    order = CONSTANT
    family = MONOMIAL
  [../]
[]

[AuxVariables]
  [./feature]
    order = CONSTANT
    family = MONOMIAL
  [../]
  [./proc_id]
    order = CONSTANT
    family = MONOMIAL
  [../]
  [./feature_ghost]
    order = CONSTANT
    family = MONOMIAL
  [../]
[]

[AuxKernels]
  [./nodal_flood_aux]
    type = FeatureFloodCountAux
    variable = feature
    flood_counter = flood_count_pp
    execute_on = 'initial timestep_end'
  [../]
  [./proc_id]
    type = ProcessorIDAux
    variable = proc_id
    execute_on = 'initial timestep_end'
  [../]
  [./ghost]
    type = FeatureFloodCountAux
    variable = feature_ghost
    field_display = GHOSTED_ENTITIES
    flood_counter = flood_count_pp
    execute_on = 'initial timestep_end'
  [../]
[]

[Functions]
  [./tif]
    type = ImageFunction
    component = 0
  [../]
[]

[ICs]
  [./u_ic]
    type = FunctionIC
    function = tif
    variable = u
  [../]
[]

[Postprocessors]
  [./flood_count_pp]
    type = FeatureFloodCount
    variable = u
    threshold = 1.0
    execute_on = 'initial timestep_end'
  [../]
[]

[Problem]
  type = FEProblem
  solve = false
[]

[Executioner]
  type = Steady
[]

[Outputs]
  csv = true
[]

(modules/phase_field/test/tests/boundary_intersecting_features/boundary_intersecting_features.i)

[Mesh]
  # ImageMesh ignores nx, xmin, xmax (and similarly for y and z) and
  # tries to read them from the image file...
  type = ImageMesh
  dim = 2

  # Be sure to choose a corresponding image name below!
  # file = image001_cropped3_closing_298.png         # full size, 157 Mb Exodus file!
  # file = eighth_image001_cropped3_closing_298.png  # 1/8
  file = sixteenth_image001_cropped3_closing_298.png # 1/16

  # Uncomment to maintain 1:1 ratio between number of pixels and mesh size.
  # scale_to_one = false

  # Uncomment to set cells_per_pixel to something other than the default value of 1.0.
  # Must be <= 1.
  # cells_per_pixel = .75

  # To crop an image to e.g. 1/8th size, install ImageMagick and run:
  #  convert image001_cropped3_closing_298.png -crop 230x198+100+100 eighth_image001_cropped3_closing_298.png
  # Note: Do not use 'sips' on OSX to crop!  It actually interpolates
  # the colors in the image instead of just cropping.
[]

[Variables]
  [./u]
    order = CONSTANT
    family = MONOMIAL
  [../]
[]

[AuxVariables]
  [./grain_auxvar]
    order = CONSTANT
    family = MONOMIAL
  [../]

  [./centroids]
    order = CONSTANT
    family = MONOMIAL
  [../]
[]

[AuxKernels]
  [./nodal_flood_aux]
    variable = grain_auxvar
    type = FeatureFloodCountAux
    flood_counter = flood_count_pp
    execute_on = 'initial timestep_end'
  [../]

  [./centroids]
    type = FeatureFloodCountAux
    variable = centroids
    flood_counter = flood_count_pp
    field_display = CENTROID
    execute_on = 'initial timestep_end'
  [../]
[]

[Functions]
  [./tif]
    # ImageFunction gets its file range parameters from ImageMesh,
    # when it is present.  This prevents duplicating information in
    # input files.
    type = ImageFunction

    # In these sample images the features we want to analyze are RED (or close to pure red). The
    # background is BLUE so we can easily distinguish between the two by selecting only the red channel.
    component = 0
  [../]
[]

[ICs]
  [./u_ic]
    type = FunctionIC
    function = tif
    variable = u
  [../]
[]

[Postprocessors]
  [./flood_count_pp]
    type = FeatureFloodCount
    variable = u
    threshold = 1.0
    compute_var_to_feature_map = true
    execute_on = 'initial timestep_end'
  [../]
[]

[VectorPostprocessors]
  [./grain_volumes]
    type = FeatureVolumeVectorPostprocessor
    flood_counter = flood_count_pp
    execute_on = 'initial timestep_end'
  [../]
[]

[Problem]
  type = FEProblem
  solve = false
[../]

[Executioner]
  type = Steady
[]

[Outputs]
  csv = true
[]

(test/tests/functions/image_function/image_mesh_3d.i)

[Mesh]
  type = ImageMesh
  dim = 3
  file_base = stack/test
  file_suffix = png
[]

[Variables]
  [u]
  []
[]

[Functions]
  [image_func]
    # ImageFunction gets its file range parameters from ImageMesh,
    # when it is present.  This prevents duplicating information in
    # input files.
    type = ImageFunction
  []
[]

[ICs]
  [u_ic]
    type = FunctionIC
    function = image_func
    variable = u
  []
[]

[Problem]
  type = FEProblem
  solve = false
[]

[Executioner]
  type = Transient
  num_steps = 1
  dt = 0.1
[]

[Outputs]
  exodus = true
[]

(test/tests/functions/image_function/image_mesh_2d.i)

[Mesh]
  type = ImageMesh
  dim = 2
  file = stack/test_00.png
[]

[Variables]
  [u]
  []
[]

[Functions]
  [image_func]
    # ImageFunction gets its file range parameters from ImageMesh,
    # when it is present.  This prevents duplicating information in
    # input files.
    type = ImageFunction
  []
[]

[ICs]
  [u_ic]
    type = FunctionIC
    function = image_func
    variable = u
  []
[]

[Problem]
  type = FEProblem
  solve = false
[]

[Executioner]
  type = Transient
  num_steps = 1
  dt = 0.1
[]

[Outputs]
  exodus = true
[]

Description
Example Syntax
Input Parameters
Input Files