README - vSLAMexample
------------------------------------------------------
vSLAMexample includes 2 simple examples using GTSAM:
- vSFMexample using visualSLAM in for structure-from-motion (SFM), and
- vISAMexample using visualSLAM and ISAM for incremental SLAM updates
The two examples use the same visual SLAM graph structure which nodes are 6d camera poses (SE3) and 3d point landmarks. Measurement factors are 2D features detected on each image, connecting its camera-pose node and the corresponding landmark nodes. There are also prior factors on each pose nodes.
Synthesized data generation
---------------------------
The data are generated by using Panda3D graphics engine to render a sequence of virtual scene with 7 colorful small 3d patches viewing by camera moving around. The patches' coordinates are given in "landmarks.txt" file. Centroids of those colorful features in the rendered images are detected and stored in "ttpy*.feat" files.
Files "ttpy*.pose" contain the poses of the virtual camera that renders the scene. A *VERY IMPORTANT* note is that the values in these "ttpy*.pose" files follow Panda3D's convention for camera frame coordinate system: "z up, y view", where as in our code, we follow OpenGL's convention: "y up, -z view". Thus, we have to change it to match with our convention. Essentially, the z- and y- axes are swapped, then the z-axis is negated to stick to the right-hand rule. Please see the function "gtsam::Pose3 readPose(const char* Fn)" in "vSLAMutils.cpp" for more information.
File "calib.txt" contains intrinsic parameters of the virtual camera. The signs are correctly adjusted to match with our projection coordinate system's convention.
Files "measurements.txt" and "poses.txt" simulate typical input data for a structure-from-motion problem. Similarly, "measurementsISAM.txt" and "posesISAM.txt" simulate the data used in SLAM context with incremental-update using ISAM.
Note that for SFM, the whole graph is solved as a whole batch problem, so the camera_id's corresponding to the feature files and pose files need to be specified in "measurements.txt" and "poses.txt", but they are not necessarily in order.
On the other hand, for ISAM, we sequentially add the camera poses and features and update after every frame; so the pose files and features files in "measurementsISAM.txt" and "posesISAM.txt" need to be specified in order (time order), even though the camera id's are not necessary.
Data file format
-----------------------------
"calib.txt":
------------
image_width image_height fx fy ox oy
"landmarks.txt"
------------
N #number of landmarks
landmark_id1 x1 y1 z1
landmark_id2 x2 y2 z2
...
landmark_idN xN yN zN
"ttpy*.feat"
------------
N #number of features
corresponding_landmark_id1 x1 y1
corresponding_landmark_id2 x2 y2
...
corresponding_landmark_idN xN yN
"ttpy*.pose"
------------
0.939693 0.34202 0 0
-0.241845 0.664463 -0.707107 0
-0.241845 0.664463 0.707107 0
34.202 -93.9693 100 1
The camera pose matrix in column order. Note that these values follows Panda3D's convention for camera coordinate frame. We have to change it to match with our convention used in the code, which follows OpenGL system. See previous section for more details.
Data For SFM:
"measurements.txt"
------------
N #number of cameras
camera_id1 featureFile1
camera_id2 featureFile2
...
camera_id3 featureFile3
"poses.txt"
------------
N #number of cameras
camera_id1 poseFile1
camera_id2 poseFile2
...
camera_id3 poseFile3
Data For ISAM:
"measurementsISAM.txt"
------------
N #number of cameras
featureFile1
featureFile2
...
featureFile3
"posesISAM.txt"
------------
N #number of cameras
poseFile1
poseFile2
...
poseFile3
3d40f5e6fc