The centralized container for the correlation plan and parameters. More...

#include <DICe_Schema.h>

Public Types
typedef Teuchos::RCP< MultiField >	mf_rcp
	Multifield RCP.

typedef Teuchos::RCP< MultiField_Map >	map_rcp
	Map RCP.

typedef Teuchos::RCP< MultiField_Exporter >	exp_rcp
	Exporter RCP.

typedef Teuchos::RCP< MultiField_Importer >	imp_rcp
	Importer RCP.

typedef Teuchos::RCP< MultiField_Comm >	comm_rcp
	Communicator RCP.

Public Member Functions
	Schema (const Teuchos::RCP< Teuchos::ParameterList > &correlation_params=Teuchos::null)
	do nothing constructor

	Schema (const Teuchos::RCP< Teuchos::ParameterList > &input_params, const Teuchos::RCP< Teuchos::ParameterList > &correlation_params)
	Constructor that takes a parameter list. More...

	Schema (const std::string &input_file_name, const std::string &params_file_name)
	Constructor that takes string name of a parameter list file. More...

	Schema (const Teuchos::RCP< Teuchos::ParameterList > &input_params, const Teuchos::RCP< Teuchos::ParameterList > &correlation_params, const Teuchos::RCP< Schema > &schema)
	Constructor that takes a parameter list. More...

	Schema (const int_t roi_width, const int_t roi_height, const int_t step_size_x, const int_t step_size_y, const int_t subset_size, const Teuchos::RCP< Teuchos::ParameterList > &params=Teuchos::null)
	Constructor that takes a parameter list and equally spaced subsets. More...

	Schema (Teuchos::ArrayRCP< scalar_t > coords_x, Teuchos::ArrayRCP< scalar_t > coords_y, const int_t subset_size, Teuchos::RCP< std::map< int_t, Conformal_Area_Def > > conformal_subset_defs=Teuchos::null, Teuchos::RCP< std::vector< int_t > > neighbor_ids=Teuchos::null, const Teuchos::RCP< Teuchos::ParameterList > &params=Teuchos::null)
	Constructor that takes a set of coordinates for the subsets and conformal definitions. More...

void	set_params (const Teuchos::RCP< Teuchos::ParameterList > &params)

void	set_params (const std::string &params_file_name)
	sets a schema's parameters with the name of a parameters xml file More...

void	update_extents (const bool use_transformation_augmentation=false)
	set the extents of the image to be used when only reading a portion of the image More...

bool	has_extents () const
	returns true if image extents are being used

std::vector< int_t >	ref_extents () const
	returns the local reference extents of the schema on this processor (defines how much of an image is actually used)

std::vector< int_t >	def_extents () const
	returns the local deformed extents of the schema on this processor (defines how much of an image is actually used)

void	set_def_image (const std::string &defName)
	Replace the deformed image for this Schema.

void	set_def_image (const int_t img_width, const int_t img_height, const Teuchos::ArrayRCP< intensity_t > defRCP, const int_t id=0)
	Replace the deformed image using an intensity array.

void	set_def_image (Teuchos::RCP< Image > img, const int_t id=0)
	Replace the deformed image using an image.

void	set_prev_image (Teuchos::RCP< Image > img, const int_t id=0)
	Replace the previous image using an image.

void	rotate_def_image ()
	Rotate the deformed image if requested.

void	set_ref_image (const std::string &refName)
	Replace the deformed image for this Schema.

void	set_ref_image (const int_t img_width, const int_t img_height, const Teuchos::ArrayRCP< intensity_t > refRCP)
	Replace the deformed image using an intensity array.

void	set_ref_image (Teuchos::RCP< Image > img)
	Replace the reference image using an image.

int_t	execute_correlation ()

int_t	execute_cross_correlation ()

void	project_right_image_into_left_frame (Teuchos::RCP< Triangulation > tri, const bool reference)

void	execute_post_processors ()
	Run the post processors.

int_t	initialize_cross_correlation (Teuchos::RCP< Triangulation > tri, const Teuchos::RCP< Teuchos::ParameterList > &input_params)

void	save_cross_correlation_fields ()
	Save off the q and r fields once the mapping from left to right image is known.

int_t	execute_triangulation (Teuchos::RCP< Triangulation > tri, Teuchos::RCP< Schema > right_schema)

int_t	execute_triangulation (Teuchos::RCP< Triangulation > tri)

void	post_execution_tasks ()
	do clean up tasks

int_t	is_initialized () const
	Returns if the field storage is initilaized.

Teuchos::RCP< Image >	ref_img () const
	Returns a pointer to the reference DICe::Image.

Teuchos::RCP< Image >	def_img (const int_t index=0) const
	Returns a pointer to the deformed DICe::Image.

const std::vector< Teuchos::RCP< Image > > *	def_imgs () const
	return a pointer to the def images vector

Teuchos::RCP< Image >	prev_img (const int_t index=0) const
	Returns a pointer to the preivous DICe::Image.

const std::vector< Teuchos::RCP< Image > > *	prev_imgs () const
	return a pointer to the def images vector

int_t	max_solver_iterations_fast () const
	Returns the max solver iterations allowed for the fast (gradient based) algorithm.

int_t	max_solver_iterations_robust () const
	Returns the max solver iterations allowed for the robust (simplex) algorithm.

double	robust_solver_tolerance () const
	Returns the robust solver convergence tolerance.

double	skip_solve_gamma_threshold () const
	Returns the threshold for gamma where the solve will be skipped if gamma < threshold.

double	fast_solver_tolerance () const
	Returns the fast solver convergence tolerance.

double	robust_delta_disp () const
	Returns the variation applied to the displacement initial guess in the simplex method.

double	robust_delta_theta () const
	Returns the variation applied to the rotation initial guess in the simplex method.

int_t	img_width () const
	Returns the reference and deformed image width.

int_t	img_height () const
	Returns the reference and deformed image height.

int_t	strain_window_size (const int_t post_processor_index) const

int_t	subset_dim () const

void	set_subset_dim (const int_t subset_dim)
	Sets the size of square subsets (not used for conformal) More...

int_t	step_size_x () const

void	set_step_size (const int_t step_size_x, const int_t step_size_y)
	Sets the step sizes for this schema. More...

void	set_step_size (const int_t step_size)
	Sets the step sizes for this schema. More...

int_t	step_size_y () const

int_t	global_num_subsets () const
	Returns the global number of correlation points.

int_t	local_num_subsets () const
	Returns the local number of correlation points.

Analysis_Type	analysis_type () const
	Returns true if the analysis is global DIC.

mv_scalar_type &	global_field_value (const int_t global_id, const DICe::field_enums::Field_Spec spec)
	Return the value of the given field at the given global id (must be local to this process) More...

mv_scalar_type &	local_field_value (const int_t local_id, const DICe::field_enums::Field_Spec spec)
	Return the value of the given field at the given local id (must be local to this process) More...

void	save_off_fields (const int_t global_id)
	Save off the current solution into the storage for frame n - 1 (only used if projection_method is VELOCITY_BASED) More...

void	print_fields (const std::string &fileName="")
	Print the field values to screen or to a file. More...

Teuchos::RCP< std::map< int_t, Conformal_Area_Def > >	conformal_subset_defs ()
	Returns a pointer to the Conformal_Subset_Def vector.

Correlation_Routine	correlation_routine () const
	Returns the correlation routine (see DICe_Types.h for valid values)

Interpolation_Method	interpolation_method () const
	Returns the interpolation method (see DICe_Types.h for valid values)

Gradient_Method	gradient_method () const
	Returns the interpolation method (see DICe_Types.h for valid values)

Optimization_Method	optimization_method () const
	Returns the optimization method (see DICe_Types.h for valid values)

Initialization_Method	initialization_method () const
	Returns the initilaization method (see DICe_Types.h for valid values)

Projection_Method	projection_method () const
	Returns the projection method (see DICe_Types.h for valid values)

void	prepare_optimization_initializers ()
	set up the initializers

Status_Flag	initial_guess (const int_t subset_gid, Teuchos::RCP< Local_Shape_Function > shape_function)

void	write_control_points_image (const std::string &fileName, const bool use_def_image=false, const bool use_one_point=false)
	Create an image that shows the correlation points. More...

void	write_output (const std::string &output_folder, const std::string &prefix="DICe_solution", const bool separate_files_per_subset=false, const bool separate_header_file=false, const bool no_text_output=false)
	Write the solution vector to a text file. More...

void	write_stats (const std::string &output_folder, const std::string &prefix="DICe_solution")
	Write the stats for a completed run. More...

void	write_deformed_subsets_image (const bool use_gamma_as_color=false)
	Write an image that shows all the subsets' current positions and shapes using the current field values. More...

void	write_reference_subset_intensity_image (Teuchos::RCP< Objective > obj)
	Write an image for each subset that shows the reference intensities for this frame. More...

void	write_deformed_subset_intensity_image (Teuchos::RCP< Objective > obj)
	Write an image for each subset that shows the deformed intensities for this frame. More...

void	write_deformed_subsets_image_new ()
	Write an image that shows all the subsets current position and shape field values from. More...

void	check_for_blocking_subsets (const int_t subset_global_id)
	See if any of the subsets have crossed each other's paths blocking each other. More...

void	generic_correlation_routine (Teuchos::RCP< Objective > obj)
	Orchestration of how the correlation is conducted. A correlation routine involves a number of steps. The first is to initialize a guess for the given subset, followed by actually performing the correlation. There are a number of checks that happen along the way. The user can request that the initial guess provide a matching gamma value that is below a certain threshold. The user can also request that the final solution meet certain criteria. There are a coupl different approaches to the correlation itself. Using the DICe::GRADIENT_BASED method is similar to most other gradient-based techniques wherein the image gradients provided by the speckle pattern drive the optimization routine to the solution. The DICe::SIMPLEX method on the other hand does not require image gradients. It uses a sophisticated bisection-like technique to arrive at the solution. More...

bool	motion_detected (const int_t subset_gid)

void	record_failed_step (const int_t subset_gid, const int_t status, const int_t num_iterations)

void	record_step (Teuchos::RCP< Objective > obj, Teuchos::RCP< Local_Shape_Function > shape_function, const scalar_t &sigma, const scalar_t &match, const scalar_t &gamma, const scalar_t &beta, const scalar_t &noise, const scalar_t &contrast, const int_t active_pixels, const int_t status, const int_t num_iterations)

bool	use_objective_regularization () const
	Returns true if regularization should be used in the objective evaluation.

bool	use_incremental_formulation () const
	returns true if the incremental formulation is used

bool	use_nonlinear_projection () const
	returns true if the nonlinear projection is used

Shape_Function_Type	shape_function_type () const
	Returns true if all quadratic shape functions are enabled.

bool	translation_enabled () const
	Returns true if translation shape functions are enabled.

bool	rotation_enabled () const
	Returns true if rotation shape functions are enabled.

bool	normal_strain_enabled () const
	Returns true if normal strain shape functions are enabled.

bool	shear_strain_enabled () const
	Returns true if shear strain shape functions are enabled.

bool	output_deformed_subset_images () const
	Print images with the deformed shape of the subset:

bool	output_evolved_subset_images () const
	Print images with the evolved intensity profile.

bool	output_beta () const
	Returns true if the beta parameter is computed by the objective.

bool	write_exodus_output () const
	Returns true if exodus output should be written.

bool	use_subset_evolution () const
	Evolve subsets as more pixels become visible that were previously obstructed.

bool	skip_all_solves () const
	Returns true if all solves should be skipped.

bool	normalize_gamma_with_active_pixels () const
	True if the gamma values should be normalized by the number of active pixels.

void	set_normalize_gamma_with_active_pixels (const bool flag)

void	set_shape_function_type (const Shape_Function_Type sft)
	Enable translation shape functions.

void	enable_translation (const bool flag)
	Enable translation shape functions.

void	enable_rotation (const bool flag)
	Enable rotation shape functions.

void	enable_normal_strain (const bool flag)
	Enable normal strain shape functions.

void	enable_shear_strain (const bool flag)
	Enable shear strain shape functions.

void	update_frame_id ()
	Updates the current image frame number.

int_t	frame_id () const
	Returns the current image frame (Nonzero only if multiple images are included in the sequence)

int_t	first_frame_id () const
	Returns the first image frame (Nonzero only if multiple images are included in the sequence)

void	set_frame_range (const int_t start_id, const int_t num_frames, const int_t frame_skip)

int_t	num_frames () const
	Returns the number of images in the set (-1 if it has not been set)

bool	has_output_spec () const
	Returns true if the output has a specific order to the fields.

double	obstruction_skin_factor () const
	Returns the size of the obstruction skin.

double	levenberg_marquardt_regularization_factor () const
	Returns the factor to use for regularization.

int_t	pixel_integration_order () const
	Returns the integration order for each pixel.

const std::vector< Teuchos::RCP< Post_Processor > > *	post_processors ()
	Return access to the post processors vector.

std::vector< int_t > *	pixels_owning_element_global_id ()
	Provide access to the list of owning elements for each pixel.

double	theta_jump_tol () const
	Return the jump tolerance for rotations.

double	disp_jump_tol () const
	Return the jump tolerance for displacements.

void	set_path_file_names (Teuchos::RCP< std::map< int_t, std::string > > path_file_names)

void	set_skip_solve_flags (Teuchos::RCP< std::map< int_t, std::vector< int_t > > > skip_solve_flags)

Teuchos::RCP< std::map< int_t, std::vector< int_t > > >	skip_solve_flags () const
	Returns a pointer to the skip solve flags.

void	set_optical_flow_flags (Teuchos::RCP< std::map< int_t, bool > > optical_flow_flags)

void	set_motion_window_params (Teuchos::RCP< std::map< int_t, Motion_Window_Params > > motion_window_params)

Teuchos::RCP< std::map< int_t, Motion_Window_Params > >	motion_window_params ()
	returns a pointer to the motion window params of the schema

bool	has_initial_condition_file () const
	returns true if an initial condition file has been specified

std::string	initial_condition_file () const
	returns the string name of the initial conditions file

void	estimate_resolution_error (const Teuchos::RCP< Teuchos::ParameterList > &correlation_params, std::string &output_folder, std::string &resolution_output_folder, std::string &prefix, Teuchos::RCP< std::ostream > &outStream)

void	set_obstructing_subset_ids (Teuchos::RCP< std::map< int_t, std::vector< int_t > > > id_vec)
	EXPERIMENTAL sets the layering order of subets. More...

void	set_force_simplex (Teuchos::RCP< std::set< int_t > > ids)
	forces simplex method for certain subsets More...

int_t	subset_global_id (const int_t local_id)

int_t	subset_local_id (const int_t global_id)

Teuchos::RCP< Teuchos::ParameterList >	get_params ()
	Returns a pointer to the params that were used to construct this schema.

Teuchos::RCP< Stat_Container >	stat_container ()
	returns a pointer to the stats class

std::vector< Teuchos::RCP< Objective > > *	obj_vec ()
	return a pointer to the objective vector

Teuchos::RCP< DICe::mesh::Mesh > &	mesh ()
	return a pointer to the mesh object that holds all the fields and maps

std::vector< int_t >	this_proc_gid_order () const
	return a copy of the gid order for this processor

Teuchos::RCP< Image_Deformer >	image_deformer () const
	returns a pointer to the image deformer used for error estimation

Private Member Functions
void	initialize (const Teuchos::RCP< Teuchos::ParameterList > &input_params, const Teuchos::RCP< Teuchos::ParameterList > &correlation_params)
	Initializes the data structures for the schema. More...

void	initialize (const Teuchos::RCP< Teuchos::ParameterList > &input_params, const Teuchos::RCP< Schema > schema)
	Initializes the data structures for the schema using another schema. More...

void	initialize (Teuchos::RCP< Decomp > decomp, const int_t subset_size, Teuchos::RCP< std::map< int_t, Conformal_Area_Def > > conformal_subset_defs=Teuchos::null)
	Initializes the data structures for the schema. More...

void	default_constructor_tasks (const Teuchos::RCP< Teuchos::ParameterList > &params)
	Sets the default values for the schema's member data and other initialization tasks. More...

void	create_mesh (Teuchos::RCP< Decomp > decomp)
	Create an exodus mesh for output. More...

void	create_mesh_fields ()
	create all of the fields necessary on the mesh

Private Attributes
comm_rcp	comm_
	Pointer to communicator (can be serial)

Teuchos::RCP< DICe::mesh::Mesh >	mesh_

std::vector< int_t >	this_proc_gid_order_
	Keeps track of the order of gids local to this process.

std::vector< Teuchos::RCP< Objective > >	obj_vec_
	Vector of objective classes.

Teuchos::RCP< Image >	ref_img_
	Pointer to reference image.

std::vector< Teuchos::RCP< Image > >	def_imgs_

std::vector< Teuchos::RCP< Image > >	prev_imgs_

std::vector< Teuchos::RCP< Post_Processor > >	post_processors_
	Vector of pointers to the post processing utilities.

bool	has_post_processor_
	True if any post_processors have been activated.

std::map< int_t, Teuchos::RCP< Initializer > >	opt_initializers_
	map of pointers to initializers (used to initialize first guess for optimization routine)

std::map< int_t, Teuchos::RCP< Motion_Test_Utility > >	motion_detectors_
	vector of pointers to motion detectors for a specific subset

std::vector< int_t >	pixels_owning_element_global_id_
	For constrained optimiation, this lists the owning element global id for each pixel:

int_t	subset_dim_
	Connectivity matrix for the global DIC method. More...

int_t	step_size_x_
	Regular grid subset spacing in x direction (used only if subsets are not conformal)

int_t	step_size_y_
	Regular grid subset spacing in y direction (used only if subsets are not conformal)

Teuchos::RCP< std::map< int_t, Conformal_Area_Def > >	conformal_subset_defs_
	Map of subset id and geometry definition.

int_t	max_evolution_iterations_
	Maximum number of iterations in the subset evolution routine.

int_t	max_solver_iterations_fast_
	Maximum solver iterations for computeUpdateFast() for an objective.

int_t	max_solver_iterations_robust_
	Maximum solver iterations for computeUpdateRobust() for an objective.

double	fast_solver_tolerance_
	Fase solver convergence tolerance.

double	robust_solver_tolerance_
	Robust solver convergence tolerance.

double	skip_solve_gamma_threshold_
	If gamma is less than this for the initial guess, the solve is skipped.

bool	skip_all_solves_
	skip the solve for all subsets and just use the initial guess as the solution

int_t	global_num_subsets_
	The global number of correlation points.

int_t	local_num_subsets_
	The local number of correlation points.

bool	has_output_spec_
	Are the output fields and columns specified by the user?

Teuchos::RCP< DICe::Output_Spec >	output_spec_
	Determines how the output is formatted.

int_t	frame_id_
	Stores current fame number for a sequence of images.

int_t	first_frame_id_
	Stores the offset to the first image's index (cine files can start with a negative index)

int_t	frame_skip_
	Stores the striding of the frames.

int_t	num_frames_
	Stores the number of images in the sequence.

double	disp_jump_tol_

double	theta_jump_tol_

double	robust_delta_disp_
	int_t of the variation to apply to the initial displacement guess used to construct the simplex

double	robust_delta_theta_
	int_t of the variation to apply to the initial rotation guess used to construct the simplex

int_t	pixel_integration_order_
	Determines how many subdivisions each pixel is cut into for integration purposes.

double	obstruction_skin_factor_
	Factor that increases or decreases the size of obstructions.

Correlation_Routine	correlation_routine_
	DICe::Correlation_Routine.

Interpolation_Method	interpolation_method_
	DICe::Interpolation_Method.

Gradient_Method	gradient_method_
	DICe::Interpolation_Method.

Optimization_Method	optimization_method_
	DICe::Optimization_Method.

Initialization_Method	initialization_method_
	DICe::Initialization_Method.

Projection_Method	projection_method_
	DICe::Projection_Method.

Analysis_Type	analysis_type_
	Analysis type.

Shape_Function_Type	shape_function_type_
	Shape function type.

bool	enable_translation_
	Enable translation.

bool	enable_rotation_
	Enable rotation.

bool	enable_normal_strain_
	Enable normal strain.

bool	enable_shear_strain_
	Enable shear strain.

Teuchos::RCP< std::map< int_t, std::vector< int_t > > >	obstructing_subset_ids_
	If subsets cross paths and obstruct each other, the obstructed pixels are removed for the blocked subset this vector stores a vector of obstructing subset ids that have the potential to block the subset associated with the outer vector index.

Teuchos::RCP< std::set< int_t > >	force_simplex_
	force simplex for these ids

bool	gauss_filter_images_
	filter the images using a gauss_filter_mask_size_ point gauss filter

bool	filter_failed_cine_pixels_
	filter the images using a gauss_filter_mask_size_ point gauss filter

int_t	gauss_filter_mask_size_
	filter the images using a gauss_filter_mask_size_ point gauss filter

bool	compute_ref_gradients_
	Compute the reference image gradients.

bool	compute_def_gradients_
	Compute the deformed image gradients.

bool	output_deformed_subset_images_
	Output images of the deformed subsets at each frame (shapes not intensity profiles)

bool	output_deformed_subset_intensity_images_
	Output images of the deformed subsets at each frame (intensity profiles)

bool	output_evolved_subset_images_
	Output images of the evolved subset at each frame.

bool	use_subset_evolution_
	Use subset evolution (Fill in the reference subset pixels as they become visible in subsequent frames)

bool	override_force_simplex_
	override the forcing of simplex method for blocking subsets

bool	normalize_gamma_with_active_pixels_
	True if the gamma values (match quality) should be normalized with the number of active pixels.

double	levenberg_marquardt_regularization_factor_
	regularization factor

bool	is_initialized_
	Solution vector and subsets are initialized.

Teuchos::RCP< Teuchos::ParameterList >	init_params_
	Pointer to the parameters whith which this schema was initialized.

Rotation_Value	ref_image_rotation_
	Rotate the reference image by 180 degrees.

Rotation_Value	def_image_rotation_
	Rotate the defomed image by 180 degrees.

Teuchos::RCP< std::map< int_t, std::string > >	path_file_names_
	Map to hold the names of the path files for each subset.

Teuchos::RCP< std::map< int_t, bool > >	optical_flow_flags_
	Map to optical flow initializers.

Teuchos::RCP< std::map< int_t, std::vector< int_t > > >	skip_solve_flags_

Teuchos::RCP< std::map< int_t, Motion_Window_Params > >	motion_window_params_

double	initial_gamma_threshold_
	tolerance for initial gamma

double	final_gamma_threshold_
	tolerance for final gamma

double	path_distance_threshold_
	tolerance for max_path_distance

bool	output_beta_
	true if the beta parameter should be computed by the objective

bool	write_exodus_output_
	true if exodus output should be written

bool	use_search_initialization_for_failed_steps_
	true if search initialization should be used for failed steps (otherwise the subset is skipped)

Teuchos::RCP< Stat_Container >	stat_container_
	keep track of stats for each subset (only for tracking routine)

bool	use_incremental_formulation_
	use the previous image as the reference rather than the original ref image

bool	sort_txt_output_
	sort the txt output for full field results by coordinates so that they are in ascending order x, then y

std::string	initial_condition_file_
	name of the file to read for the initial condition

bool	use_nonlinear_projection_
	project the right image onto the left frame of reference using a nonlinear projection

bool	has_extents_
	true if only certain portions of the images should be loaded (for example in parallel for large images)

std::vector< int_t >	ref_extents_
	vector that contains the x and y extents for the reference images (x_start_ref, x_end_ref, y_start_ref, y_end_ref)

std::vector< int_t >	def_extents_
	vector that contains the x and y extents for the deformed images (x_start_def, x_end_def, y_start_def, y_end_def)

int_t	full_ref_img_width_
	store the total image dims (the image size before decomposition across processors)

int_t	full_ref_img_height_
	store the total image dims (the image size before decomposition across processors)

Teuchos::RCP< Image_Deformer >	image_deformer_
	store a pointer to the image deformer if this is a error estimation run

bool	compute_laplacian_image_
	true if the laplacian images should be computed

int_t	threshold_block_size_
	size of threshold to use for feature matching when thresholding is included

Detailed Description

The centralized container for the correlation plan and parameters.

This class holds all of the correlation parameters and provides the basic structure for how the correlation steps are executed. Each schema holds a pointer to a reference and deformed DICe::Image. Many of the pre-correlation steps are also done by a DICe::Schema (for example filtering the images, or computing the gradients).

All of the field values are stored by a DICe::Schema which provides an interface to external data structures as well.

Several methods are provided that expose the parameters.

Constructor & Destructor Documentation

◆ Schema() [1/5]

DICe::Schema::Schema	(	const Teuchos::RCP< Teuchos::ParameterList > &	input_params,
		const Teuchos::RCP< Teuchos::ParameterList > &	correlation_params
	)

Constructor that takes a parameter list.

Parameters

input_params	the input parameters contain the image file names and subset size and spacing, etc.
correlation_params	the correlation parameters determine the dic algorithm options

◆ Schema() [2/5]

DICe::Schema::Schema	(	const std::string &	input_file_name,
		const std::string &	params_file_name
	)

Constructor that takes string name of a parameter list file.

Parameters

input_file_name	file name of the input.xml file that contains subset locations file names, etc.
params_file_name	file name of the correlation parameters file

◆ Schema() [3/5]

DICe::Schema::Schema	(	const Teuchos::RCP< Teuchos::ParameterList > &	input_params,
		const Teuchos::RCP< Teuchos::ParameterList > &	correlation_params,
		const Teuchos::RCP< Schema > &	schema
	)

Constructor that takes a parameter list.

Parameters

input_params	the input parameters contain the image file names and subset size and spacing, etc.
correlation_params	the correlation parameters determine the dic algorithm options
schema	pointer to another schema

◆ Schema() [4/5]

DICe::Schema::Schema	(	const int_t	roi_width,
		const int_t	roi_height,
		const int_t	step_size_x,
		const int_t	step_size_y,
		const int_t	subset_size,
		const Teuchos::RCP< Teuchos::ParameterList > &	params = `Teuchos::null`
	)

Constructor that takes a parameter list and equally spaced subsets.

Parameters

roi_width	the region of interest width
roi_height	the region of interest height
step_size_x	Spacing of the correlation points in x
step_size_y	Spacing of the correlation points in y
subset_size	int_t of the square subsets in pixels
params	Correlation parameters

◆ Schema() [5/5]

DICe::Schema::Schema	(	Teuchos::ArrayRCP< scalar_t >	coords_x,
		Teuchos::ArrayRCP< scalar_t >	coords_y,
		const int_t	subset_size,
		Teuchos::RCP< std::map< int_t, Conformal_Area_Def > >	conformal_subset_defs = `Teuchos::null`,
		Teuchos::RCP< std::vector< int_t > >	neighbor_ids = `Teuchos::null`,
		const Teuchos::RCP< Teuchos::ParameterList > &	params = `Teuchos::null`
	)

Constructor that takes a set of coordinates for the subsets and conformal definitions.

Parameters

coords_x	the x positions of the subset centroids
coords_y	the y positions of the subset centroids
subset_size	int_t of the subsets, (use -1 if conformals are defined for all subsets, otherwise all subsets without a conformal subset def will be square and assigned this subset size.
conformal_subset_defs	Optional definition of conformal subsets
neighbor_ids	A vector (of length num_pts) that contains the neighbor id to use when initializing the solution by neighbor value
params	correlation parameters

Member Function Documentation

◆ check_for_blocking_subsets()

void DICe::Schema::check_for_blocking_subsets ( const int_t subset_global_id )

See if any of the subsets have crossed each other's paths blocking each other.

The potential for two subsets to block each other should have been set by calling set_obstructing_subset_ids() on the schema by this point. WARNING: This is meant only for the TRACKING_ROUTINE where there are only a few subsets to track

◆ create_mesh()

void DICe::Schema::create_mesh ( Teuchos::RCP< Decomp > decomp )

private

Create an exodus mesh for output.

Parameters

decomp pointer to a decomposition note: the current parallel design for the subset-based methods is that all subsets are owned by all elements, this enables using the overlap map to collect the solution from other procs because the overlap map and the all owned map are the same. The dist_map is used to define the distributed ownership for which procs will correlate a given subset. This map is one-to-one with no overlap

◆ default_constructor_tasks()

void DICe::Schema::default_constructor_tasks ( const Teuchos::RCP< Teuchos::ParameterList > & params )

private

Sets the default values for the schema's member data and other initialization tasks.

Parameters

params Optional correlation parameters

◆ estimate_resolution_error()

void DICe::Schema::estimate_resolution_error	(	const Teuchos::RCP< Teuchos::ParameterList > &	correlation_params,
		std::string &	output_folder,
		std::string &	resolution_output_folder,
		std::string &	prefix,
		Teuchos::RCP< std::ostream > &	outStream
	)

estimate the error in the displacement resolution and strain

Parameters

correlation_params	parameters to apply to the resolution estimation
output_folder	where to place the output files
resolution_output_folder	where to place the spatial resolution output
prefix	the file prefix to use for output files
outStream	output stream to write screen output to

◆ execute_correlation()

int_t DICe::Schema::execute_correlation ( )

Conduct the correlation returns 0 if successful

◆ execute_cross_correlation()

int_t DICe::Schema::execute_cross_correlation ( )

Conduct the cross correlation (a modified version of the regular correlation) returns 0 if successful

◆ execute_triangulation()

int_t DICe::Schema::execute_triangulation	(	Teuchos::RCP< Triangulation >	tri,
		Teuchos::RCP< Schema >	right_schema
	)

Triangulate the current positions of the subset centroids returns 0 if successful

Parameters

tri	pointer to a triangulation
right_schema	pointer to the right camera's schema (holds the displacement info)

◆ generic_correlation_routine()

void DICe::Schema::generic_correlation_routine ( Teuchos::RCP< Objective > obj )

Orchestration of how the correlation is conducted. A correlation routine involves a number of steps. The first is to initialize a guess for the given subset, followed by actually performing the correlation. There are a number of checks that happen along the way. The user can request that the initial guess provide a matching gamma value that is below a certain threshold. The user can also request that the final solution meet certain criteria. There are a coupl different approaches to the correlation itself. Using the DICe::GRADIENT_BASED method is similar to most other gradient-based techniques wherein the image gradients provided by the speckle pattern drive the optimization routine to the solution. The DICe::SIMPLEX method on the other hand does not require image gradients. It uses a sophisticated bisection-like technique to arrive at the solution.

Another major difference between correlation routine options is denoted by DICe::GENERIC_ROUTINE or DICe::TRACKING_ROUTINE. The generic option is intended for full-field displacement cases where there are a number of subsets per image, but not necessarily a lot of images. In this case the subsets are allocated each image or frame. The tracking case is intended for a handful of subsets, but potentially several thousand frames. In this case the subsets are allocated once at the beginning and re-used throughout the analysis.

At a number of points in the process, the subset may evolve in the sense that pixels on an object that become occluded are switched off. Other pixels that initially were blocked and become visible at some point get switched on (this is activated by setting use_subset_evolution in the params file).

Parameters

obj	A single DICe::Objective that has a DICe::subset as part of its member data

◆ global_field_value()

mv_scalar_type& DICe::Schema::global_field_value	(	const int_t	global_id,
		const DICe::field_enums::Field_Spec	spec
	)

inline

Return the value of the given field at the given global id (must be local to this process)

Parameters

global_id	Global ID of the element
spec	the Field_Spec of the field to get the value for

◆ initial_guess()

Status_Flag DICe::Schema::initial_guess	(	const int_t	subset_gid,
		Teuchos::RCP< Local_Shape_Function >	shape_function
	)

get an initial guess for the solution

Parameters

subset_gid	the global id of the subset to initialize
deformation	[out] vector containing the intial guess

◆ initialize() [1/3]

void DICe::Schema::initialize	(	const Teuchos::RCP< Teuchos::ParameterList > &	input_params,
		const Teuchos::RCP< Schema >	schema
	)

private

Initializes the data structures for the schema using another schema.

Parameters

input_params	pointer to the initialization parameters
schema	pointer to another schema

◆ initialize() [2/3]

void DICe::Schema::initialize	(	const Teuchos::RCP< Teuchos::ParameterList > &	input_params,
		const Teuchos::RCP< Teuchos::ParameterList > &	correlation_params
	)

private

Initializes the data structures for the schema.

Parameters

input_params	pointer to the initialization parameters
correlation_params	pointer to the correlation parameters

◆ initialize() [3/3]

void DICe::Schema::initialize	(	Teuchos::RCP< Decomp >	decomp,
		const int_t	subset_size,
		Teuchos::RCP< std::map< int_t, Conformal_Area_Def > >	conformal_subset_defs = `Teuchos::null`
	)

private

Initializes the data structures for the schema.

Parameters

decomp	pointer to the decomposition class object
subset_size	int_t of the subsets, (use -1 if conformals are defined for all subsets, otherwise all subsets without a conformal subset def will be square and assigned this subset size.
conformal_subset_defs	Optional definition of conformal subsets
neighbor_ids	A vector (of length num_pts) that contains the neighbor id to use when initializing the solution by neighbor value

◆ initialize_cross_correlation()

int_t DICe::Schema::initialize_cross_correlation	(	Teuchos::RCP< Triangulation >	tri,
		const Teuchos::RCP< Teuchos::ParameterList > &	input_params
	)

Create intial guess for cross correlation using epipolar lines and the camera parameters returns 0 if successful

Parameters

tri	Triangulation that contains the camera params
input_params	the input params are needed to load the right image for processor 0

◆ local_field_value()

mv_scalar_type& DICe::Schema::local_field_value	(	const int_t	local_id,
		const DICe::field_enums::Field_Spec	spec
	)

inline

Return the value of the given field at the given local id (must be local to this process)

Parameters

local_id	local ID of the subset
spec	the Field_Spec of the requested field

◆ motion_detected()

bool DICe::Schema::motion_detected ( const int_t subset_gid )

Returns true if the user has requested testing for motion in the frame and the motion was detected by diffing pixel values:

Parameters

subset_gid the global id of the subset to test for motion

◆ print_fields()

void DICe::Schema::print_fields ( const std::string & fileName = "" )

Print the field values to screen or to a file.

Parameters

fileName Optional file name

If fileName is empty, write the fields to the screen. If fielName is not empty, write the fields to a file (appending)

◆ project_right_image_into_left_frame()

void DICe::Schema::project_right_image_into_left_frame	(	Teuchos::RCP< Triangulation >	tri,
		const bool	reference
	)

projects the right image into the left frame (useful when the mapping between is highly nonlinear)

Parameters

tri	a pointer to a triangulation that contains the projective parameters
reference	true if the transformation should be applied to the reference image

◆ record_failed_step()

void DICe::Schema::record_failed_step	(	const int_t	subset_gid,
		const int_t	status,
		const int_t	num_iterations
	)

Fail the current frame for this subset and move on to the next

Parameters

subset_gid	the global id of the subset
status	the reason for failure
num_iterations	the number of iterations that took place before failure

◆ record_step()

void DICe::Schema::record_step	(	Teuchos::RCP< Objective >	obj,
		Teuchos::RCP< Local_Shape_Function >	shape_function,
		const scalar_t &	sigma,
		const scalar_t &	match,
		const scalar_t &	gamma,
		const scalar_t &	beta,
		const scalar_t &	noise,
		const scalar_t &	contrast,
		const int_t	active_pixels,
		const int_t	status,
		const int_t	num_iterations
	)

Record the solution in the field arrays

Parameters

obj	pointer to an objective class
shape_function	pointer to a shape function
sigma	sigma value
match	match value
gamma	gamma value
beta	beta value
noise	noise level value
contrast	the contrast level value
active_pixels	the number of active pixels for this subset
status	status flag
num_iterations	the number of iterations

◆ save_off_fields()

void DICe::Schema::save_off_fields ( const int_t global_id )

inline

Save off the current solution into the storage for frame n - 1 (only used if projection_method is VELOCITY_BASED)

Parameters

global_id global ID of correlation point

◆ set_force_simplex()

void DICe::Schema::set_force_simplex ( Teuchos::RCP< std::set< int_t > > ids )

inline

forces simplex method for certain subsets

Parameters

ids	Pointer to set of ids

◆ set_frame_range()

void DICe::Schema::set_frame_range	(	const int_t	start_id,
		const int_t	num_frames,
		const int_t	frame_skip
	)

inline

Sets the first frame's index

Parameters

start_id	the index of the first frame (useful for cine files)
num_frames	the total number of frames in the analysis

◆ set_motion_window_params()

void DICe::Schema::set_motion_window_params ( Teuchos::RCP< std::map< int_t, Motion_Window_Params > > motion_window_params )

inline

Provide access to the the dimensions of windows around each subset used to detect motion between frames

◆ set_normalize_gamma_with_active_pixels()

void DICe::Schema::set_normalize_gamma_with_active_pixels ( const bool flag )

inline

True if the gamma values should be normalized by the number of active pixels

Parameters

flag	true if the gamma values should be normalized by the number of active pixels

◆ set_obstructing_subset_ids()

void DICe::Schema::set_obstructing_subset_ids ( Teuchos::RCP< std::map< int_t, std::vector< int_t > > > id_vec )

inline

EXPERIMENTAL sets the layering order of subets.

Parameters

id_vec Pointer to map of vectors, each vector contains the ids for that particular subset in the order they will be layered if they cross paths

If two subsets have the potential to cross each other's path, the Schema needs to know which one will be on top so that the pixels obscured on the lower subset can be turned off

◆ set_optical_flow_flags()

void DICe::Schema::set_optical_flow_flags ( Teuchos::RCP< std::map< int_t, bool > > optical_flow_flags )

inline

Provide access to the flags that determine if optical flow should be used as an initializer:

Parameters

optical_flow_flags the map of optical flow flags

◆ set_params() [1/2]

void DICe::Schema::set_params ( const std::string & params_file_name )

sets a schema's parameters with the name of a parameters xml file

Parameters

params_file_name File name of the paramteres file

◆ set_params() [2/2]

void DICe::Schema::set_params ( const Teuchos::RCP< Teuchos::ParameterList > & params )

If a schema's parameters are changed, set_params() must be called again any params that aren't set are reset to the default value (so this method can be used with a null params to reset the schema's parameters).

Parameters

params pointer to the prameterlist

◆ set_path_file_names()

void DICe::Schema::set_path_file_names ( Teuchos::RCP< std::map< int_t, std::string > > path_file_names )

inline

Provide access to the list of path file names:

Parameters

path_file_names the map of path file names

◆ set_skip_solve_flags()

void DICe::Schema::set_skip_solve_flags ( Teuchos::RCP< std::map< int_t, std::vector< int_t > > > skip_solve_flags )

inline

Provide access to the flags that determine if the solve should be skipped:

Parameters

skip_solve_flags the map of skip solve flags

◆ set_step_size() [1/2]

void DICe::Schema::set_step_size ( const int_t step_size )

inline

Sets the step sizes for this schema.

Parameters

step_size Step size in the x and y-direction

◆ set_step_size() [2/2]

void DICe::Schema::set_step_size	(	const int_t	step_size_x,
		const int_t	step_size_y
	)

inline

Sets the step sizes for this schema.

Parameters

step_size_x	Step size in the x-direction
step_size_y	Step size in the y-direction

◆ set_subset_dim()

void DICe::Schema::set_subset_dim ( const int_t subset_dim )

inline

Sets the size of square subsets (not used for conformal)

Parameters

subset_dim Square size of the subsets

◆ step_size_x()

int_t DICe::Schema::step_size_x ( ) const

inline

Returns the step size in x direction for a square subset

If this is a conformal analysis or if the subsets are not in a regular grid this returns -1

◆ step_size_y()

int_t DICe::Schema::step_size_y ( ) const

inline

Returns the step size in y direction for a square subset

If this is a conformal analysis or if the subsets are not in a regular grid this returns -1

◆ strain_window_size()

int_t DICe::Schema::strain_window_size ( const int_t post_processor_index ) const

Returns the size of the strain window in pixels for the selected post_processor

Parameters

post_processor_index The index of the post processor to get the window size for

◆ subset_dim()

int_t DICe::Schema::subset_dim ( ) const

inline

Returns the size of a square subset

This is called subset_dim to discourage use as a call to subset_size subset_size does not exist for a conformal subset (there is no notion of width and height for conformal)

◆ subset_global_id()

int_t DICe::Schema::subset_global_id ( const int_t local_id )

inline

Return the global id of a subset local id

Parameters

local_id the input local id to tranlate to global

◆ subset_local_id()

int_t DICe::Schema::subset_local_id ( const int_t global_id )

inline

Return the local id of a subset global id

Parameters

global_id the input global id to tranlate to local

◆ update_extents()

void DICe::Schema::update_extents ( const bool use_transformation_augmentation = false )

set the extents of the image to be used when only reading a portion of the image

Parameters

use_transformation_augmentation true if the right image is being projected into the left frame of reference for each frame (typicaly only set to true for nonlinear projection in the cross correlation)

◆ write_control_points_image()

void DICe::Schema::write_control_points_image	(	const std::string &	fileName,
		const bool	use_def_image = `false`,
		const bool	use_one_point = `false`
	)

Create an image that shows the correlation points.

Parameters

fileName	String name of file to for output
use_def_image	True if the deformed image should be used, otherwise the reference image is used
use_one_point	True if only one correlation point should be used (helpful if the point density is high)

WARNING: This only works for square subsets.

◆ write_deformed_subset_intensity_image()

void DICe::Schema::write_deformed_subset_intensity_image ( Teuchos::RCP< Objective > obj )

Write an image for each subset that shows the deformed intensities for this frame.

Parameters

obj	pointer to the objective

◆ write_deformed_subsets_image()

void DICe::Schema::write_deformed_subsets_image ( const bool use_gamma_as_color = false )

Write an image that shows all the subsets' current positions and shapes using the current field values.

WARNING: This is meant only for the TRACKING_ROUTINE where there are only a few subsets to track

Parameters

use_gamma_as_color colors the pixels according to gamma values for each pixel

◆ write_deformed_subsets_image_new()

void DICe::Schema::write_deformed_subsets_image_new ( )

Write an image that shows all the subsets current position and shape field values from.

WARNING: This is meant only for the TRACKING_ROUTINE where there are only a few subsets to track

◆ write_output()

void DICe::Schema::write_output	(	const std::string &	output_folder,
		const std::string &	prefix = `"DICe_solution"`,
		const bool	separate_files_per_subset = `false`,
		const bool	separate_header_file = `false`,
		const bool	no_text_output = `false`
	)

Write the solution vector to a text file.

Parameters

output_folder	Name of the folder for output (the file name is fixed)
prefix	Optional string to use as the file prefix
separate_files_per_subset	Forces the output to be one file per subset listing each frame on a new row. The default is one file per frame with all subsets listed one per row.
separate_header_file	place the run information in another file rather than the header of the results
no_text_output	if true the text output files are not written

◆ write_reference_subset_intensity_image()

void DICe::Schema::write_reference_subset_intensity_image ( Teuchos::RCP< Objective > obj )

Write an image for each subset that shows the reference intensities for this frame.

Parameters

obj	pointer to the objective

◆ write_stats()

void DICe::Schema::write_stats	(	const std::string &	output_folder,
		const std::string &	prefix = `"DICe_solution"`
	)

Write the stats for a completed run.

Parameters

output_folder	Name of the folder for output (the file name is fixed)
prefix	Optional string to use as the file prefix

Member Data Documentation

◆ def_imgs_

std::vector<Teuchos::RCP<Image> > DICe::Schema::def_imgs_

private

Pointer to deformed image vector because there could be multiple sub-images

◆ disp_jump_tol_

double DICe::Schema::disp_jump_tol_

private

Displacement jump tolerance. If the displacement solution is larger than this from the previous frame it is rejected

◆ mesh_

Teuchos::RCP<DICe::mesh::Mesh> DICe::Schema::mesh_

private

The mesh holds the fields and subsets or elements and nodes For a schema using the subset formulation the parallel strategy is as follows: the subsets are split up into even goups on all procs. If seeds are involved or obstructions, the ordering and allocation of groups respects the order needed for seeds or obstructions. In the mesh an element and node are created for each subset for exodus output. The connectivity of the element only has one node and its gid corresponds to the subset gid (same for nodes). The element map and node distribution maps are forced to be identical in this case. In the element map, the processor ownership of subsets is one-to-one, i.e. each element is owned by only one processor. The dist node map matches the dist elem map (and is one-to-one). The overlap node map assigns all nodes to all processors. This map is used for post-processors and output from process 0 or anywhere an all to all communication is needed.

◆ motion_window_params_

Teuchos::RCP<std::map<int_t,Motion_Window_Params> > DICe::Schema::motion_window_params_

private

Map to hold the flags that determine if the next image should be tested for motion before doing the DIC

◆ prev_imgs_

std::vector<Teuchos::RCP<Image> > DICe::Schema::prev_imgs_

private

Pointer to previous image vector because there could be multiple sub-images

◆ skip_solve_flags_

Teuchos::RCP<std::map<int_t,std::vector<int_t> > > DICe::Schema::skip_solve_flags_

private

Map to hold the flags for skipping solves for particular subsets (initialize only since only pixel accuracy may be needed

◆ subset_dim_

int_t DICe::Schema::subset_dim_

private

Connectivity matrix for the global DIC method.

Square subset size (used only if subsets are not conformal)

◆ theta_jump_tol_

double DICe::Schema::theta_jump_tol_

private

Theta jump tolerance. If the theta solution is larger than this from the previous frame it is rejected

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Schema() [1/5]

◆ Schema() [2/5]

◆ Schema() [3/5]

◆ Schema() [4/5]

◆ Schema() [5/5]

Member Function Documentation

◆ check_for_blocking_subsets()

◆ create_mesh()

◆ default_constructor_tasks()

◆ estimate_resolution_error()

◆ execute_correlation()

◆ execute_cross_correlation()

◆ execute_triangulation()

◆ generic_correlation_routine()

◆ global_field_value()

◆ initial_guess()

◆ initialize() [1/3]

◆ initialize() [2/3]

◆ initialize() [3/3]

◆ initialize_cross_correlation()

◆ local_field_value()

◆ motion_detected()

◆ print_fields()

◆ project_right_image_into_left_frame()

◆ record_failed_step()

◆ record_step()

◆ save_off_fields()

◆ set_force_simplex()

◆ set_frame_range()

◆ set_motion_window_params()

◆ set_normalize_gamma_with_active_pixels()

◆ set_obstructing_subset_ids()

◆ set_optical_flow_flags()

◆ set_params() [1/2]

◆ set_params() [2/2]

◆ set_path_file_names()

◆ set_skip_solve_flags()

◆ set_step_size() [1/2]

◆ set_step_size() [2/2]

◆ set_subset_dim()

◆ step_size_x()

◆ step_size_y()

◆ strain_window_size()

◆ subset_dim()

◆ subset_global_id()

◆ subset_local_id()

◆ update_extents()

◆ write_control_points_image()

◆ write_deformed_subset_intensity_image()

◆ write_deformed_subsets_image()

◆ write_deformed_subsets_image_new()

◆ write_output()

◆ write_reference_subset_intensity_image()

◆ write_stats()

Member Data Documentation

◆ def_imgs_

◆ disp_jump_tol_

◆ mesh_

◆ motion_window_params_

◆ prev_imgs_

◆ skip_solve_flags_

◆ subset_dim_

◆ theta_jump_tol_