Release of OpenCorr GUI 1.0

4_Processing_methods.md

@@ -74,6 +74,7 @@ Member functions:
 - updateTranslationVector(), update translation vector;
 - updateProjectionMatrix(), update projection matrix according to the three matrices mentioned above;
 - updateMatrices(), update all the four matrices;
+- clear(), set the values of all intrinsics and extrinsics to be zero.
 - Point2D image_to_sensor(Point2D& point), convert the coordinates of input point from image/retina system to sensor/pixel system;
 - Point2D sensor_to_image(Point2D& point), convert the coordinates of input point from sensor/pixel system to image/retina system;
 - float getConvergence(), get current convergence criterion;
@@ -116,15 +117,15 @@ Member functions:
 
 - setPath(string file_path), set path of CSV datasheet;
 - setDelimiter(string delimiter), set delimiter for data picking
-- loadTable2D(), loadTable2DS(), or loadTable3D(), load computed results at POIs from a CSV datasheet, create a POI2D, POI2DS, or POI3D queue;
 - loadPoint2D(string file_path) or loadPoint3D(string file_path), load coordinates of POIs from a CSV datasheet of given file path, create a Point2D or Point3D queue;
+- savePoint2D(vector<POI2D> point_queue, string file_path) or savePoint3D(vector<POI3D> point_queue, string file_path), save the coordinates of POIs to a CSV datasheet of given file path;
+- loadCalibration(Calibration& calibration_cam1, Calibration& calibration_cam2, string file_path), load calibration parameters of cameras from a CSV file;
+- loadTable2D(), loadTable2DS(), or loadTable3D(), load computed results at POIs from a CSV datasheet, create a POI2D, POI2DS, or POI3D queue;
 - saveTable2D(vector<POI2D> poi_queue), saveTable2DS(vector<POI2DS> poi_queue), or saveTable3D(vector<POI3D> poi_queue)，save the information of POIs into a CSV datasheet;
 - saveDeformationTable2D(vector<POI2D> poi_queue), save the full deformation vectors of POIs into a CSV datasheet;
-- saveMap2D(vector<POI2D> poi_queue, char variable), save specific information of POIs (2D DIC results) into a 2D map according to the coordinates of POIs, variable can be set as 'u', 'v', 'c'(zncc), 'd'(convergence), 'i'(iteration), 'f'(feature), 'x' (exx), 'y' (eyy), 'r' (exy);.
-- saveMap2DS(vector<POI2DS>& poi_queue, char variable), save specific information of POIs (3D/stereo DIC results) into a 2D map according to the coordinates of POIs, variable can be set as 'u', 'v', 'w', 'c'(r1r2_zncc), 'd'(r1t1_zncc), 'e'(r1t2_zncc), 'x' (exx), 'y' (eyy), 'z' (ezz), 'r' (exy) , 's' (eyz), 't' (ezx);
-- saveMap3D(vector<POI3D>& poi_queue, char variable), save specific information of POIs (DVC results) into a 3D map according to the coordinates of POIs, variable can be set as 'u', 'v', 'w', 'c'(zncc), 'x' (exx), 'y' (eyy), 'z' (ezz), 'r' (exy) , 's' (eyz), 't' (ezx);
-- saveMatrixBin(vector<POI3D>& poi_queue), save the information of POIs into a binary file. The binary file begins with a head of four integers (data length and three dimensions along x, y, and z directions), followed with an array of floats.
-- vector<POI3D> loadMatrixBin(), read the information of POIs from a binary file, store the information into a POI queue. The dimensions of image got from the head of binary file are stored in dim_x, dim_y, and dim_z of IO object.
+- saveMap2D(vector<POI2D> poi_queue, OutputVariable out_var), saveMap2DS(vector<POI2DS>& poi_queue, OutputVariable out_var), or saveMap3D(vector<POI3D>& poi_queue, OutputVariable out_var), save specific information of POIs (results of 2D DIC, 3D/stereo DIC, or DVC) into a 2D or 3D map according to the coordinates of POIs, out_variable can be set according to enum OutputVariable;
+- saveMatrixBin(vector<POI3D>& poi_queue), save the information of POIs into a binary file. The binary file begins with a head of four integers (data length and three dimensions along x, y, and z directions), the rest part of file are float data of each POIs, in order of : x, y, z, u, v, w, zncc, convergence.
+- vector<POI3D> loadMatrixBin(), read the information of POIs from a binary file, store the information into a POI queue. The data structure is same to that in saveMatrixBin().
 
 ![image](./img/oc_io.png)
 
@@ -136,17 +137,18 @@ Figure 4.2.1 shows the parameters and methods included in the base classes of DI
 
 - Pointer of reference image and target image: ref_img 和 tar_img;
 - Subset radii (in x, y and z direction): subset_radius_x, subset_radius_y, subset_radius_z;
-- Number of CPU threads in parallel processing: thread_number.
+- Number of CPU threads in parallel processing: thread_number;
+- Switch of self-adaptive subset mode: self_adaptive.
 
 Member functions:
 
 - setImages(Image& ref_img, Image& tar_img), set the pointers of ref_img and tar_img;
 
-- setSubsetRadius(int subset_radius_x, int subset_radius_y) or setSubsetRadius(int subset_radius_x, int subset_radius_y, int subset_radius_z), set subset radii.
+- setSubset(int subset_radius_x, int subset_radius_y) or setSubset(int subset_radius_x, int subset_radius_y, int subset_radius_z), set subset radii.
 
-  The following are three virtual functions,
+- setSelfAdaptive(bool is_self_adpative), turn on or off the mode of self-adaptive subset; 
 
-- prepare(), preparation for DIC or DVC processing;
+  The following are three virtual functions,prepare(), preparation for DIC or DVC processing;
 
 - compute(POI2D* poi) or compute(POI3D* poi), process a single POI;
 
@@ -201,7 +203,7 @@ Figure 4.2.7 shows the parameters and methods included in Strain (oc_strain.h an
 Parameters:
 
 - Radius of subregion for fitting of local displacement profiles: subregion_radius;
-- Minimum number of neighbor POIs involved in facet fitting: min_neighbor_num;
+- Minimum number of neighbor POIs involved in facet fitting: neighbor_number_min;
 - Lowest ZNCC value required for the neighbor POIs involved in facet fitting: zncc_threshold;
 - Description of strain tensor: description, 1 denotes Lagrangian; 2 denotes Eulerian;
 - Approximation of strain: approximation, 1 for Cauchy strain; 2 for Green strain;
@@ -210,7 +212,7 @@ Parameters:
 Member functions:
 
 - setSubregionRadius(int subregion_radius), set the radius of the POI-centered subregion for fitting of local displacement profiles;
-- setMinNeighborNumber(int min_neighbor_num), set minimum number of neighbor POIs;
+- setNeighborMin(int neighbor_number_min), set minimum number of neighbor POIs;
 - setZnccThreshold(float zncc_threshold), set ZNCC threshold;
 - setDescription(int description), set description of strain tensor: 1 denotes Lagrangian; 2 denotes Eulerian;
 - setApproximation(int approximation), set definition of strains: 1 for Cauchy strain; 2 for Green strain;

5_GPU_acceleration.md

@@ -4,7 +4,7 @@ GPU accelerated modules currently include ICGN2D algorithm (with shape functions
 Requirements:
 
 - Hardware: NVIDIA graphics card with memory greater than 2GB
-- Software: Windows OS, CUDA ToolKit 12.3
+- Software: Windows 10 or newer, CUDA ToolKit 12.3 or new
 
 GPU accelerated ICGN module consists of three files: head (opencorr_gpu.h), static library (OpenCorrGPU.lib), and dynamic link library (OpenCorrGPU.dll). The configuration in Visual Studio can be summarized as four steps:
 

7_Software_with_GUI.md

@@ -0,0 +1,57 @@
+# 7. Software with GUI
+
+OpenCorr with GUI is developed using the frame of [Dear ImGui](https://github.com/ocornut/imgui). It aims to facilitate the user to process their experimental data. Users may download the package from [Releases on GitHub](https://github.com/vincentjzy/OpenCorr/releases) or the Download page on [opencorr.org](https://opencorr.org/Download). Unzip it (e.g. using 7-Zip) and run OpenCorr.exe, make sure that the other two DLL files are in the same folder of  OpenCorr.exe. This software is developed by a small team (Mr LI Rui, Mr REN Haoqiang and me). Its function and usage experience are far from perfect at the moment. Any comments and suggestions are greatly appreciated.
+
+Figure 7.1 shows the interface to run 2D DIC. One reference image and a bunch of target images can be loaded and displayed in the righthand side window. You may press the CTRL or SHIFT key to select multiple files in file dialog.
+
+![image](./img/gui_dic_2d_1.png)
+
+*Figure 7.1. Interface of 2D DIC in multiple view*
+
+
+
+You may also shift to single view for convenience to set DIC parameters, as shown in Figure 7.2. A yellow rectangle appear in the center of window once the box of "Show subset" is checked. Then, you can change its size to see if there is a unique speckle pattern within it.
+
+![image](./img/gui_dic_2d_2.png)
+
+*Figure 7.2. Interface of 2D DIC in single view*
+
+
+
+Figure 7.3 shows the interface to run 3D/stereo DIC. The images in left column are regarded as primary view, and the ones in right column are secondary view.
+
+![image](./img/gui_dic_3d_1.png)
+
+*Figure 7.3. Interface of 3D/stereo DIC in multiple view*
+
+
+
+To run 3D/stereo DIC, calibration parameters of cameras need to loaded from a CSV file (Figure7.4). An example of datasheet is given in the package (*_Calibration.csv in package).
+
+![image](./img/gui_dic_3d_2.png)
+
+*Figure 7.4. Load calibration parameters of cameras for 3D/stereo DIC*
+
+
+
+You may draw the region of interest (ROI) and set the space between the POIs to create a matrix of uniformly distributed POIs, as shown in Figure 7.5. Yellow areas represent the ROI, and blue areas are excluded from ROI. The coordinates of POIs can be exported to a CSV file if you would like to use them in future.
+
+![image](./img/gui_dic_3d_3.png)
+
+*Figure 7.5. Draw region of interest (ROI) in single view (yellow area means the ROI, blue area means the excluded part)*
+
+
+
+Figure 7.6 shows the interface in for stereo reconstruction to measure the 3D shape of an object. In addition to drawing ROI and setting POI space, the POIs can be loaded from a previously saved CSV file.
+
+![image](./img/gui_stereo_reconstruction.png)
+
+*Figure 7.6. Interface of stereo reconstruction （multiple view）. POIs can be loaded from a CSV file*
+
+
+
+Figure 7.7 shows the interface for strain calculation. You may recalculate the strains based on the previously obtained DIC results. Parameters like subregion size and ZNCC threshold can be adjusted to get reliable results, according to the yellow circle and points within it (they will be displayed when the box "Show subregion" is checked).
+
+![image](./img/gui_strain_calculation.png)
+
+*Figure 7.6. Interface of strain calculation. DIC results need to be loaded from CSV files*

README.md

@@ -49,6 +49,8 @@ Users can also access the information of OpenCorr via website [opencorr.org](htt
 >2023.03.06, A research paper titled "OpenCorr: An open source library for research and development of digital image correlation" is published in Optics and Lasers in Engineering.
 >
 >2024.02.07, Major update of ICGN module: (i) GPU accelerated ICGN (ICGNGPU) has been completely reconstructed, adding the function of DVC. The calling method of ICGNGPU is now similar to the CPU version. Most of redundant data conversion and transfer are eliminated. Two examples are added to the folder /examples to demonstrate the use of ICGNGPU. (ii) CPU version is modified to improve the efficiency.
+>
+>2024.06.14, Release GUI of OpenCorr. Codes and examples are modified.
 
 # Instructions
 
@@ -58,6 +60,7 @@ Users can also access the information of OpenCorr via website [opencorr.org](htt
 4. [Processing methods](./4_Processing_methods.md)
 5. [GPU acceleration](./5_GPU_acceleration.md)
 6. [Examples](./6_Examples.md)
+7. [Software with GUI](./7_Software_with_GUI.md)
 
 # Developers
 
@@ -68,6 +71,8 @@ Users can also access the information of OpenCorr via website [opencorr.org](htt
 - Mr HUANG Jianwen, Software engineer, SenseTime
 - Mr YANG Junrong, Software engineer, Tencent
 - Mr LIN Aoyu, Engineer, China Southern Power Grid
+- Mr LI Rui, PhD candidate, South China University of Technology
+- Mr REN Haoqiang, PhD candidate, South China University of Technology
 
 # Acknowledgements
 
@@ -117,6 +122,9 @@ We are jubilant at that OpenCorr helps other colleagues in their study as a soft
 9. Hengrui Cui, Zhoumo Zeng, Jian Li, Hui Zhang, Fenglong Yang, Shili Chen. The effect of error coefficient matrices and correlation criteria on dic computation errors. Optics and Lasers in Engineering (2024) 174: 107954. (https://doi.org/10.1016/j.optlaseng.2023.107954)
 10. Datao Li, Xiahui Wei, Yingrong Gao, Jinsong Jiang, Wei Xia, Binhua Wang. Investigations on tensile mechanical properties of rigid insulation tile materials at elevated temperatures based on digital image correlation algorithm. Construction and Building Materials (2024) 413: 134925. (https://doi.org/10.1016/j.conbuildmat.2024.134925)
 11. Jiashuai Yang, Kemao Qian, Lianpo Wang. R3-DICnet: an end-to-end recursive residual refinement DIC network for larger deformation measurement. Optics Express (2024) 32(1): 907-921. (https://doi.org/10.1364/OE.505655)
+12. Yahong Feng, Lianpo Wang. Stereo-DICNet: An efficient and unified speckle matching network for stereo digital image correlation measurement. Optics and Lasers in Engineering (2024) 179: 108267. (https://doi.org/10.1016/j.optlaseng.2024.108267)
+13. Longyong Tong, Hang Zhou, Brian Sheil. Multicore CPU-based parallel computing accelerated digital image correlation for large soil deformations measurement. Computers and Geotechnics (2024) 166: 106027. (https://doi.org/10.1016/j.compgeo.2023.106027)
+14. Siqi Wang, Zehui Zhu, Tao Ma, Jianwei Fan. Asphalt concrete characterization using digital image correlation: A systematic review of best practices, applications, and future vision. Journal of Testing and Evaluation (2024) 52(4): 20230485. (https://doi.org/10.1520/JTE20230485)
 
 Counting of visitors started from 03 Aug, 2023
 ![Visitor Count](https://profile-counter.glitch.me/vincentjzy/count.svg)

examples/test_2d_dic_fftcc_icgn1.cpp

@@ -118,14 +118,14 @@ int main()
 	//save the map of u-component
 	file_path = tar_image_path.substr(0, tar_image_path.find_last_of(".")) + "_fftcc_icgn1_r16_u.csv";
 	in_out.setPath(file_path);
-	char var_char = 'u';
-	in_out.saveMap2D(poi_queue, var_char);
+	OutputVariable out_var = u;
+	in_out.saveMap2D(poi_queue, out_var);
 
 	//save the map of v-component
 	file_path = tar_image_path.substr(0, tar_image_path.find_last_of(".")) + "_fftcc_icgn1_r16_v.csv";
 	in_out.setPath(file_path);
-	var_char = 'v';
-	in_out.saveMap2D(poi_queue, var_char);
+	out_var = v;
+	in_out.saveMap2D(poi_queue, out_var);
 
 	//save the computation time
 	file_path = tar_image_path.substr(0, tar_image_path.find_last_of(".")) + "_fftcc_icgn1_r16_time.csv";

examples/test_2d_dic_self_adaptive_subset.cpp

@@ -70,12 +70,16 @@ int main()
 	sift->setImages(ref_img, tar_img);
 
 	FeatureAffine2D* feature_affine = new FeatureAffine2D(subset_radius_x, subset_radius_y, cpu_thread_number);
-	int neighbor_num = 2 * feature_affine->getMinNeighborNumber();
-	feature_affine->setSearchParameters(sqrt(subset_radius_x * subset_radius_x + subset_radius_y * subset_radius_y), neighbor_num);
+	int neighbor_num = 2 * feature_affine->getNeighborMin();
+	int radius_min = 10;
+	feature_affine->setSearch(sqrt(subset_radius_x * subset_radius_x + subset_radius_y * subset_radius_y), neighbor_num);
 	feature_affine->setImages(ref_img, tar_img);
+	feature_affine->setSelfAdaptive(true);
+	feature_affine->setSubsetAdjustment(neighbor_num, radius_min);
 
 	ICGN2D1* icgn1 = new ICGN2D1(subset_radius_x, subset_radius_y, max_deformation_norm, max_iteration, cpu_thread_number);
 	icgn1->setImages(ref_img, tar_img);
+	icgn1->setSelfAdaptive(true);
 
 	float search_radius = 25;
 	int min_neighbors = 5;
@@ -111,8 +115,7 @@ int main()
 	//dynamic optimization of subset at each POI based on modified FeatureAffine
 	feature_affine->setKeypointPair(sift->ref_matched_kp, sift->tar_matched_kp);
 	feature_affine->prepare();
-	int min_radius = 10;
-	feature_affine->compute(poi_queue, neighbor_num, min_radius);
+	feature_affine->compute(poi_queue);
 
 	//conventional DIC method with fixed-size subset
 	//feature_affine->compute(poi_queue);
@@ -123,15 +126,14 @@ int main()
 	computation_time.push_back(consumed_time); //2
 
 	//display the time of initialization on the screen
-	cout << "Subset optimization and deformation estimation at" << poi_queue.size() << " POIs takes " << consumed_time << " sec" << std::endl;
+	cout << "Subset optimization and deformation estimation at " << poi_queue.size() << " POIs takes " << consumed_time << " sec" << std::endl;
 
 	//get the time of start 
 	timer_tic = omp_get_wtime();
 
 	//ICGN with the 2nd order shape fucntion
 	icgn1->prepare();
-	Point2D subset_radius(0, 0);
-	icgn1->compute(poi_queue, subset_radius);
+	icgn1->compute(poi_queue);
 
 	//conventional DIC method with fixed-size subset
 	//icgn1->compute(poi_queue);

examples/test_2d_dic_strain.cpp

@@ -80,8 +80,8 @@ int main()
 	file_path = tar_image_path.substr(0, tar_image_path.find_last_of(".")) + "_eyy.csv";
 	in_out.setPath(file_path);
 
-	//variable: 'u', 'v', 'c'(zncc), 'd'(convergence), 'i'(iteration), 'f'(feature), 'x' (exx), 'y' (eyy), 'r' (exy)
-	in_out.saveMap2D(poi_queue, 'y');
+	OutputVariable out_var = e_yy;
+	in_out.saveMap2D(poi_queue, out_var);
 
 	//save the computation time
 	file_path = tar_image_path.substr(0, tar_image_path.find_last_of(".")) + "_strain_r20_time.csv";

src/oc_calibration.cpp

@@ -90,6 +90,12 @@ namespace opencorr
 		updateMatrices();
 	}
 
+	void Calibration::clear()
+	{
+		std::fill(std::begin(intrinsics.cam_i), std::end(intrinsics.cam_i), 0.f);
+		std::fill(std::begin(extrinsics.cam_e), std::end(extrinsics.cam_e), 0.f);
+	}
+
 	float Calibration::getConvergence() const
 	{
 		return convergence;

src/oc_calibration.h

@@ -73,6 +73,9 @@ namespace opencorr
 		void updateMatrices();
 		void updateCalibration(CameraIntrinsics& intrinsics, CameraExtrinsics& extrinsics);
 
+		//reset all elements of intrinsics and extrinsics to be zero
+		void clear();
+
 		//get and set convergence criterion and stop condition
 		float getConvergence() const;
 		int getIteration() const;

src/oc_cubic_bspline.cpp

@@ -358,8 +358,8 @@ namespace opencorr
 	float TricubicBspline::compute(Point3D& location)
 	{
 		float value = 0.f;
-		if (location.x < 0 || location.y < 0 || location.z < 0
-			|| location.x >= interp_img->dim_x || location.y >= interp_img->dim_y || location.z >= interp_img->dim_z
+		if (location.x < 1 || location.y < 1 || location.z < 1
+			|| location.x >= interp_img->dim_x - 2 || location.y >= interp_img->dim_y - 2 || location.z >= interp_img->dim_z - 2
 			|| std::isnan(location.x) || std::isnan(location.y) || std::isnan(location.z))
 		{
 			value = -1.f;

src/oc_dic.cpp

@@ -30,6 +30,11 @@ namespace opencorr
 		subset_radius_y = radius_y;
 	}
 
+	void DIC::setSelfAdaptive(bool is_self_adaptive)
+	{
+		self_adaptive = is_self_adaptive;
+	}
+
 
 
 	DVC::DVC() {}
@@ -48,7 +53,8 @@ namespace opencorr
 	}
 
 
-	bool sortByZNCC(const POI2D& p1, const POI2D& p2) {
+	bool sortByZNCC(const POI2D& p1, const POI2D& p2)
+	{
 		return p1.result.zncc > p2.result.zncc;
 	}
 

src/oc_dic.h

@@ -24,6 +24,17 @@
 
 namespace opencorr
 {
+
+	// definition of abnormal ZNCC value
+	// 0: reset for further processing
+	// -1: insufficient features in subset (FeatureAffine)
+	// -2: inconsistant set in RANSAC (FeatureAffine)
+	// -3: terminated at the beginning of (ICGN)
+	// -4: Not convergence in iteration (ICGN)
+	// -5: NaN in resutls (ICGN)
+	// -6: insufficient reliable neighbor POIs (RegionFit)
+	// -7: insufficient reliable neighbor POIs (Strain)
+
 	//structure for brute force searching
 	struct KeypointIndex
 	{
@@ -39,12 +50,14 @@ namespace opencorr
 
 		int subset_radius_x, subset_radius_y;
 		int thread_number; //OpenMP thread number
+		bool self_adaptive;
 
 		DIC();
 		virtual ~DIC() = default;
 
 		void setImages(Image2D& ref_img, Image2D& tar_img);
 		void setSubset(int radius_x, int radius_y);
+		void setSelfAdaptive(bool is_self_adaptive); //select if the subset is automatically set or manually set
 
 		virtual void prepare() = 0;
 		virtual void compute(POI2D* poi) = 0;

src/oc_epipolar_search.cpp

@@ -43,7 +43,7 @@ namespace opencorr
 		if (search_radius < search_step)
 		{
 			std::cerr << "Search radius is less than search step" << std::endl;
-			exit(1);
+			return;
 		}
 		this->search_radius = search_radius;
 		this->search_step = search_step;