Image Based Detection of 3D Scene Change, IEEJ Transactions on Electronics, Information and Systems, Vol. 133, No. 1, pp.103-110 (2013).
http://https://github.com/linbaowei/changeDetection
Baowei Lin, Yuji Ueno, Kouhei Sakai, Toru Tamaki, Bisser Raytchev, Kazufumi Kaneda, Koji Ichii (Hiroshima University)
Contact address: [email protected]
===================================================================



*IMPORTANT
	3D keypoints are important for change detection. Please download the project of 3D keypoints from https://github.com/linbaowei/3DkeypointsGeneration firstly.



* What can you get
-------------------------------------------------------------------
	We develop a method for 3D scene change detectioin. We particularly target the case when a 3D scene can be changed by disasters and accidents. Assuming that there is a 3D point cloud of the 3D scene reconstructed before the change by using a set of training images, the camera positions of newly taken query images with small changes can be estimated. To find a region of change in the query images, first, the nearest image of a query image is selected from the training images. Then, the matching between the query image and the nearest image is computed for finding a set of non-matching points as a region of change. These change regions are visualized by projecting 3D points back only to those regions.

	If you download zip file of our propsed method and uncompress it, you can find a folder named "changeDetection", a black-white checker board picture. The files are explained in following parts.










* Requirements
-------------------------------------------------------------------
	1. OpenCV 2.4.0
	2. Boost C++ Libraries 1.47.0
	3. SIFTGPU
	4. ANN
	5. 3D point cloud
	6. 2D training images used for 3D reconstruction
	7. camera positions for 2D training images
	8. 3D keypoints and descriptor file
	(1, 2, 3 and 4 are libs which can be downloaded and installed from their homepage. 5, 6, 7 and 8 can be obtained from our existing method called "3D keypoints detection from a 3D point cloud for real-time camera tracking". You can download it from https://github.com/linbaowei/3DkeypointsGeneration, and use it according to README.txt.)








* How to use 3D keypoint generation method
-------------------------------------------------------------------

	usage:
	-----------------------------------------------------------
		./changedetection
		--plyFileof3DpointCloudFile		[YOURINPUT]	//input: generated 3D point clouds file (ply file in Bundler)
		--3DKeypointsFile			[YOURINPUT]	//input: generated 3D keypoints and their descriptors (.key file generated by 3D keypoints method, see https://github.com/linbaowei/3DkeypointsGeneration)
		--trainingImagesKeysPath		[YOURINPUT]	//input: 2D SIFT keypoints files of training images (training images folder in Bundler)
		--testImagesPath			[YOURINPUT]	//input: path used to save test image (the detection target)
		--topNearestImagesNum		[YOURINPUT]	//input: the number of performances of nearest images. Basically, 1 is enough. But sometimes, the best performance is not from the nearest images. We suggest to set it as 5, and please to select the best performance by yourself.





	Example:
	----------------------------------------------------------- 
		suppose the path of bundler folder is "/home/user/bundler/". The generated 3D keypoints' path is "/home/user/3DKeypointsGeneration/". 		
		So let us see the follow example:
		./changedetection    --plyFileof3DpointCloudFile /home/user/bundler/training3Dpoints/PMVS2output_level2.ply 
					--3DKeypointsFile 		/home/user/3DKeypointsGeneration/output_4_1 
					--trainingImagesKeysPath    /home/user/bundler/training3Dpoints/PMVS2inputImages/ 
		                   	--testImagesPath             /home/user/testImage/ 
					--topNearestImagesNum       3
	

	'training3Dpoints/PMVS2output_level2.ply' is generated 3D point cloud by Bundler and PMVS2.
	'3DKeypointsGeneration/output_4_1' is the file generated by using our existing method "3D Keypoints detection from a 3D point cloud for real time camera tracking". The outputs of 3D keypoints detection method is: output_[threshold1]_[threshold2]. threshold1={1,2,...,#training images}, threshold2={0.5, 0.7, 1, 3, 5}. Based on different value of the thresholds, the number of generated 3D keypoints are different. Please select appropriate thresholds for yourself.
	'/training3Dpoints/PMVS2inputImages/' is a folder created by our existing method "3D Keypoints detection from a 3D point cloud for real time camera tracking". The 2D SIFT features files are saved in this folder.
	'testImagesPath' is a folder created for storing test image. It is the detection target. Please just keep one test image in this folder.
	'topNearestImagesNum' is the number of performances of nearest images. Basically, 1 is enough. But sometimes, the best performance is not from the nearest images. We suggest to set it as 5, and please to select the best performance by yourself.


	


	How to compile change detection project
	-----------------------------------------------------------
		in order to compile 3D keypoint generation project, at least, OpenCV 2.4.0, SIFTGPU, Boost C++ Libraries 1.47.0 and ANN (Appropriate Nearest Neighbor) are necessary.
		bash-4.2$  cd /changeDetection	//depand on where you save our provided files
		bash-4.2$  mkdir build
		bash-4.2$  cd build
		bash-4.2$  cmake ..
		bash-4.2$  make
		bash-4.2$  mkdir calibration
		bash-4.2$  cp -r [your photos for calibration] /calibration		//before using our method, it is necessary to calibrate your camera, a picture of black-white checker boards is provided in the downloaded files, please print it out and use your camera to take several images of it. Then copy these new taken images into calibration folders. Our method will automatically call these images. 
		bash-4.2$  ./changedetection ......






	The result you can get
	----------------------------------------------------------
		you can get some images with only red points superimposed. The red points means the changed region. THe formate of these images is: result_[testimage name].key[nearest image number].key[threshold of th_v].jpg. Please select the best performance for yourself.





* License: MIT
--------------------------------------------------------------------

/*
 *   Copyright (c) 2012 <Baowei Lin> <[email protected]>
 * 
 *   Permission is hereby granted, free of charge, to any person
 *   obtaining a copy of this software and associated documentation
 *   files (the "Software"), to deal in the Software without
 *   restriction, including without limitation the rights to use,
 *   copy, modify, merge, publish, distribute, sublicense, and/or sell
 *   copies of the Software, and to permit persons to whom the
 *   Software is furnished to do so, subject to the following
 *   conditions:
 * 
 *   The above copyright notice and this permission notice shall be
 *   included in all copies or substantial portions of the Software.
 * 
 *   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
 *   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 *   OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 *   NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
 *   HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
 *   WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 *   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 *   OTHER DEALINGS IN THE SOFTWARE.
 */



We kindly ask for users to refer
Baowei Lin, Yuji Ueno, Kouhei Sakai, Toru Tamaki, Bisser Raytchev, Kazufumi Kaneda, Koji Ichii: Image Based Detection of 3D Scene Change, IEEJ Transactions on Electronics, Information and Systems, Vol. 133, No. 1, pp.103-110 (2013).
in your paper publised by using our implementation. Thank you!