dicengine / dice

Digital Image Correlation Engine (DICe): a stereo DIC application that runs on Mac, Windows, and Linux

DICe

Pushing DIC technology to new levels, together

DICe (pronounced /dīs/ as in "roll the dice") is an open source digital image correlation (DIC) tool intended for use as a module in an external application or as a standalone analysis code. Its primary capabilities are computing full-field displacements and strains from sequences of digital images and rigid body motion tracking of objects. The images analyzed are typically of a material sample undergoing a characterization experiment, but DICe is also useful for other applications (for example, trajectory tracking). DICe is machine portable (Windows, Linux, and Mac) and can be effectively deployed on a high performance computing platform (DICe uses MPI parallelism as well as threaded on-core parallelism). Capabilities from DICe can be invoked through a customized library interface, via source code integration of DICe classes or through a standalone executable.

There are two ways to install and use DICe. If you are on a Windows or Mac OS and simply want to install DICe and use it there are package installers available on the release page. If you are using Linux or would like to make your own custom modifications to DICe, you can build DICe and the DICe GUI using the instructions on the documentation page below.

Although the GUI is expanding with each new version, only the basic use cases for 2d and stereo DIC are currently available as options in the GUI. To use DICe for trajectory tracking, or to enable some of the advanced features like the regularized global methods, the command line interface needs to be used. Instructions are given in the tutorials for how to enable options like these. A good way to get started is to use the GUI to set up some basic input files and then modify these files as necessary to enable more advanced features.

Features

DICe is different than other available DIC codes in the following ways:

First, subsets can be of arbitrary shape. This enables tracking of oblong objects that otherwise would not be trackable with a square subset.

DICe also incudes a robust simplex optimization method that does not use image gradients (this method is useful for data sets that are impossible to analyze with the traditional Lucas-Kanade-type algorithms, for example, objects without speckles, images with low contrast, and small subset sizes < 10 pixels).

Lastly, DICe also includes a well-posed global DIC formulation that addresses instabilities associated with the saddle-point problem in DIC (This capability will be released later this year).

For more technical information see: https://github.com/dicengine/dice/tree/master/doc/reports

Documentation

http://dicengine.github.io/dice

How To Videos

2D analysis: https://youtu.be/TD7HDwPxx1Q

Stereo analysis: https://youtu.be/8FGbIwk3fcU

2D tracking: https://youtu.be/ZBhFYplj04g

General Use, Tips for DIC, and Other Resources

The International DIC Society (iDICs) provides a number of helpful resources related to DIC, for example a comprehesive guide on best practives, www.idics.org/guide, as well as conferences and workshops related to DIC. Go to www.idics.org for more information.

Command Line Use Tutorials

http://dicengine.github.io/dice/pages.html

Releases (and Installers)

Windows and Mac OS package installers for DICe can be found here. To install DICe on Linux, it must be built from source following the instructions here.

Contributing to DICe

Fork the DICe repo, develop new algorithms and send us a pull request. We suggest the following guidelines be followed to keep a high degree of software quality:

• Ensure that all existing tests pass with your changes applied
• Create tests for new features
• Document code with Doxygen formatted comments
• Have your changes reviewed by an objective party
• Use descriptive commit messages

Reporting Bugs or Requesting New Features

Use the issues link above to report bugs and request new features.

Citing DICe:

DZ Turner, Digital Image Correlation Engine (DICe) Reference Manual, Sandia Report, SAND2015-10606 O, 2015

dice's Issues

Several asserts in the code should rather throw exceptions

The asserts do not get compiled in release mode, but there are several cases where the code really should throw an exception if the given assert case occurs.

More interpolants

Implement the 8tap and 4tap optimized interpolants from Hubert's book.

The frame number from a .cine file is not carried through to the output

If the cine begins its indexing from frame -100, the first frame in the output is still frame 0. This can be confusing. It would be better if the output frame index matched the index from the .cine file itself.

Provide Error Message If Invalid XML files

Please, can you set the code to provide error message if there are non- valid xml lines. Right now the code crashes without a warning.

Thanks.

Alvaro

Create an initializer that uses zeros for all displacement parameters on every step.

Put simulation information in a separate file rather than the output file

All of the header information from the output files would be better placed in a separate file along with git information about the state of the code as compiled. This would avoid issues with csv file readers that do not handle header lines.

Report the contrast level of a subset as a field

Add rotation to phase correlation initializer

Currently, the phase correlation initializer only does u and v, but not theta. The methods are avaiable in dicefft library to do rotations as well, they just haven't been enabled in the initializers like they should.

Strange full-field strain results

Hi DICe team,

I'm attempting to run the full-field strain tutorial (example 3) using the latest version of the GUI (2.0-5) on MacOS 10.11.6

I load the reference and deformed images from the tutorial and define inclusion/exclusion regions as below:

with the following processing options:

The displacement data look reasonable, but the computed strain field is quite noisy and doesn't make a lot of sense:

I've tried a few different combinations of settings, but the strain results look similar to that above regardless. I also tried previous versions of the 2.0 beta (2.0-3, 2.0-4), but it seemed like the Exodus output was corrupt in these versions (at least with a small step size).

Are there any known issues with the strain results in the current Mac release?

Kind regards,
Ken

shape function with second-order displacement gradient

Thanks for the great source. I think it will be great to add shape function with second order displacement gradient.

Links to the tutorial and custom app examples should be put in the README

"Large" translations not recognized

Hi Dan and team,

I am performing some more tests with DICe and have noticed that large translations (>~30px) between two image frames are not recognized.

For instance, in the following image pair,^* a simple rigid-body translation is applied (32-pixel shift to the left):

Feature matching initialization seems to work fine:

but the displacement field is empty:

The behavior seems to be independent of subset and step size, initialization method, etc. But if a smaller (e.g., 20px) translation is applied instead, the displacements are extracted as expected.

Any ideas as to why this is occurring? Is there a way to overcome this limitation?

Thanks,
Ken

^*Note: source image from Pan et al. 2010, Opt Lasers Eng.

Report the number of active pixels for a subset as a field

A screenshot of the GUI should go on the homepage

Move interpolants to free functions to reduce code copying (Serial only)

For the kokkos enabled base classes, the interpolant cannot be a free function

Recompute image gradients after transformation

If an image is transformed by rotating or translating using the DICe::Image->apply_transformation() method, the gradients should be re-computed in case they are used after the transformation.

Version numbers need to be added to the code output

There may be a way to include the git sha1 in the output

Stereo DIC is really tricky to get working in the current version of DICe

Please develop a simpler way to do stereo DIC in DICe without having to do so much of the process manually with different input files batched together. It would also be helpful if the stereo DIC was enabled through a graphical user interface.

DICe needs a graphical user interface

Most users (not developers or super-users) would benefit greatly from having a GUI to create input files and view the results.

Example showing how to use obstructions

Frame indexing is not correct if the user requests starting from a particular frame

If the reference and starting index are the first frame in the video for a cine file, this does not happen. If however a specific frame is requested for the starting frame, the indexing always starts from the first frame of the cine video

Normalize by active pixels should be disabled for simplex sigma calcs

If the user has turned on gamma normalization by active pixels, this should be turned off when computing the sigma value for the simplex method. Otherwise the sigma values will be different depending on if the normalization is tuned on and this should not be the case.

Batch file for windows build setup

Aside from using a command line with the right tools loaded, (ie intel compiler) there should be a batch file that one can run to make sure all the executables and libraries are in the PATH and LIB env variables for building DICe on windows.

The .tiff extension is missing from exporting the reference and deformed subset intensities

This issue only occurs when the reference or deformed subset intensities are written to a file for debugging.

obstruction_skin_factor for each tracking

Is it possible to assign a different obstruction_skin_factor (or not at all) for each tracked part?

Thanks.

Alvaro

Create a search initializer

Remove the search methods from DICe::Objective as well

Contrast level doesn't account for deactivated pixels

If there is an obstruction across a subset, it's intensity values are being included in the contrast level calculations. @aacruzc

Version 2.0-beta.5 issue

I installed the 2.0 beta 5 version from the installer packages on a windows 10 (64 bit) machine. After loading the ref. and def. images and selecting a ROI I try to correlate (all other opties stay default). I immediately get following message : DICe execution failed (see console for details).

When looking at the console, the only messages I get are:
writing input file C:\PATH\input.xml
input.xml file has been successfully saved
writing parameters file C:\PATH\params.xml
params.xml file has been successfully saved
writing subset file C:\PATH\subset_defs.txt
subset_defs.txt file has been successfully saved

For the rest everything looks normal.
Please advise what I'm doing wrong.
Thanks
Bart

Filter Option for High Speed Cameras

Is it possible to set as an option to activate a filter that replaces all the pixels that reach the maximum (2^10 or 2^12) possible with adjacent pixels? The user should be able to "disable" or "enable" the filter by a Boolean variable in the params.xml file.

Thanks.

Alvaro

Example files missing from windows package installer

The tutorial examples do not get shipped with the package installer for windows.

ROI not visulaised

In the last version (beta6) when I define the ROI this is not displayed in green like in the previous versions so is difficult to verify the corect position.
Maybe the problem is related to the fact that I'm working with WIN10.

Conversion to 8 bit depth from actual 12 depth in a 16 bit container

Will like to convert .cine videos that are defined 16 bit, but contain only 12 bit depth data into 8 bit depth.

Thanks

Alvaro

Read .jpg .bmp and .png files

Example of using DICe in an external code

There should be an example in the code where DICe is used by including DICe headers in an external application

Which IDE I can compiler these codes in Windows

Sir:
Which IDE I can compiler this codes in Windows,I should extend the function of these codes. Thanks a lot!
best wishes!

Regards
Liu

Problems with Subset leaving Image

HI,
I have noticed that if the a small portion of the part that you are tracking leaves the field of view/ image then dice will crash. This is a minor issue so don't spend to much time on it.
Thanks

Change the way pixel intensity values are accessed from an image

As it is now, it's not clear that the ->intensity_array() method returns non-const access to the intensity values of the image. There should be two methods, one that returns a const copy of the intensity values and one that provides access to change them.

dice.dll with new builds

Hi,
Can you fix the installer to include the dice.dll for future use. I think the one you sent in an email was missing something.
Thanks
Scott

Create an optical flow initializer

Phase correlation should be an initializer

In DICe::Schema, there is a lot of code that could be encapsulated in a DICe::Initializer related to when phase correlation of the whole image is used for the initial guess. Remove the member data like phase_cor_u_x_, etc. and put this in a new initializer class.

cine_start_index is being ignored

Even if the user adds the input parameter cine_start_index, the analysis starts at the beginning of the video rather than the specified start index.

Speed up the simplex method

The simplex method takes several iterations more than the gradient based methods, because of this DICe should look at ways to make it faster and more competitive

dice execution failed

Thanks a lot for great software. I download the version 2 beta 5 and install it with windows 10.
After I load reference image, deform image, set roi and dic parameters, the dice execution failed.
There is not noticeable comment in the console.
I run the dice.exe file from the installation directory ,but the error "VCOMP120.DLL was not found" is shown.
please help me for this problem
best regard.

When image gradients are zero (constant intensity) sigma gets reported as INF

erros when install on ubuntu

Thank you very much for your code and I love it very much.
After configuring and generating via cmake, I use sudo make to install it but errors occur like this:

[ 32%] Linking CXX executable ../../bin/dice
/usr/bin/ld: /usr/lib/x86_64-linux-gnu/libtiff.a(tif_pixarlog.o): undefined reference to symbol 'inflateEnd'
/usr/local/lib/libz.so.1: error adding symbols: DSO missing from command line
collect2: error: ld returned 1 exit status
src/core/CMakeFiles/dice_main.dir/build.make:177: recipe for target 'bin/dice' failed
make[2]: *** [bin/dice] Error 1
CMakeFiles/Makefile2:297: recipe for target 'src/core/CMakeFiles/dice_main.dir/all' failed
make[1]: *** [src/core/CMakeFiles/dice_main.dir/all] Error 2
Makefile:127: recipe for target 'all' failed
make: *** [all] Error 2

Could you please tell me what to do next?
Thank you very much.

invalid field name and some comments on new calibration layout

Hey,

I installed the windows (10) version release 2 beta 6. Good job with the calibration tool btw.
Is it correct that the size of the calibration target and the spacing for the markers in X and Y direction are not available anymore?
I also only see half of the right and left preview windows when scrolling down to the bottom of the page. Has this something to do with screen resolution or so?

I'm also having the following error when trying to correlate stereo images:

Output will be written to one file per frame with all subsets included
Execution information will be written to a separate file (not placed in the output headers)
Error: invalid field name requested in output spec: MODEL_COORDINATE_X
C:\Users\dzturne\Software\DICe_nightly\src\core\DICe_Schema.cpp:3325:

Throw number = 1

Throw test that evaluated to true: true

Please advise what can be wrong...

Thanks
Bart

binary files

Hi,

could you please include Win32 or Win64 binaries with MPI enabled into the release section of Github? That would significantly speed up the learning process of your great DIC engine.

Best regards,
Oldrich

Several asserts in Parser.cpp should be exceptions

A strategy for exception handling in general is needed

Create a warning if the subset centroid is outside of the subset boundary

Average image feature

Enable the user to select several images to be averaged to get the reference image