Skip to content

Commit 57e841d

Browse files
koide3koide3
committed
docs of detailed algorithm behavior for py
1 parent f6a48e5 commit 57e841d

File tree

7 files changed

+123
-58
lines changed

7 files changed

+123
-58
lines changed

‎src/python/align.cpp

+20-12
Original file line numberDiff line numberDiff line change
@@ -100,10 +100,13 @@ void define_align(py::module& m) {
100100
py::arg("verbose") = false,
101101
R"pbdoc(
102102
Align two point clouds using various ICP-like algorithms.
103+
This function first performs preprocessing (downsampling, normal estimation, KdTree construction) and then estimates the transformation.
104+
105+
See also: :class:`voxelgrid_sampling` :class:`estimate_normals` :class:`preprocess_points`
103106
104107
Parameters
105108
----------
106-
target_points : numpy.ndarray[np.float64]
109+
target_points : :class:`numpy.ndarray[np.float64]`
107110
Nx3 or Nx4 matrix representing the target point cloud.
108111
source_points : numpy.ndarray[np.float64]
109112
Nx3 or Nx4 matrix representing the source point cloud.
@@ -115,6 +118,7 @@ void define_align(py::module& m) {
115118
Resolution of voxels used for correspondence search (used only in VGICP).
116119
downsampling_resolution : float = 0.25
117120
Resolution for downsampling the point clouds.
121+
Input points out of the 21bit range after discretization will be ignored (See also: :class:`voxelgrid_sampling`).
118122
max_correspondence_distance : float = 1.0
119123
Maximum distance for matching points between point clouds.
120124
num_threads : int = 1
@@ -126,7 +130,7 @@ void define_align(py::module& m) {
126130
127131
Returns
128132
-------
129-
result : RegistrationResult
133+
result : :class:`RegistrationResult`
130134
Object containing the final transformation matrix and convergence status.
131135
)pbdoc");
132136

@@ -175,15 +179,17 @@ void define_align(py::module& m) {
175179
py::arg("verbose") = false,
176180
R"pbdoc(
177181
Align two point clouds using specified ICP-like algorithms, utilizing point cloud and KD-tree inputs.
182+
Input point clouds are assumed to be preprocessed (downsampled, normals estimated, KD-tree built).
183+
See also: :class:`voxelgrid_sampling` :class:`estimate_normals` :class:`preprocess_points`
178184
179185
Parameters
180186
----------
181-
target : PointCloud::ConstPtr
182-
Pointer to the target point cloud.
183-
source : PointCloud::ConstPtr
184-
Pointer to the source point cloud.
185-
target_tree : KdTree<PointCloud>::ConstPtr, optional
186-
Pointer to the KD-tree of the target for nearest neighbor search. If nullptr, a new tree is built.
187+
target : :class:`PointCloud`
188+
Target point cloud.
189+
source : :class:`PointCloud`
190+
Source point cloud.
191+
target_tree : :class:`KdTree`, optional
192+
KdTree for the target point cloud. If not given, a new KdTree is built.
187193
init_T_target_source : numpy.ndarray[np.float64]
188194
4x4 matrix representing the initial transformation from target to source.
189195
registration_type : str = 'GICP'
@@ -199,7 +205,7 @@ void define_align(py::module& m) {
199205
200206
Returns
201207
-------
202-
result : RegistrationResult
208+
result : :class:`RegistrationResult`
203209
Object containing the final transformation matrix and convergence status.
204210
)pbdoc");
205211

@@ -231,12 +237,14 @@ void define_align(py::module& m) {
231237
py::arg("verbose") = false,
232238
R"pbdoc(
233239
Align two point clouds using voxel-based GICP algorithm, utilizing a Gaussian Voxel Map.
240+
Input source point cloud is assumed to be preprocessed (downsampled, normals estimated, KD-tree built).
241+
See also: :class:`voxelgrid_sampling` :class:`estimate_normals` :class:`preprocess_points`
234242
235243
Parameters
236244
----------
237-
target_voxelmap : GaussianVoxelMap
245+
target_voxelmap : :class:`GaussianVoxelMap`
238246
Voxel map constructed from the target point cloud.
239-
source : PointCloud
247+
source : :class:`PointCloud`
240248
Source point cloud to align to the target.
241249
init_T_target_source : numpy.ndarray[np.float64]
242250
4x4 matrix representing the initial transformation from target to source.
@@ -251,7 +259,7 @@ void define_align(py::module& m) {
251259
252260
Returns
253261
-------
254-
result : RegistrationResult
262+
result : :class:`RegistrationResult`
255263
Object containing the final transformation matrix and convergence status.
256264
)pbdoc");
257265
}

‎src/python/factors.cpp

+37-14
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,12 @@ using namespace small_gicp;
2020

2121
void define_factors(py::module& m) {
2222
// DistanceRejector
23-
py::class_<DistanceRejector>(m, "DistanceRejector", "Correspondence rejection based on the distance between points.")
23+
py::class_<DistanceRejector>(
24+
m,
25+
"DistanceRejector",
26+
R"pbdoc(
27+
Correspondence rejection based on the distance between points.
28+
)pbdoc")
2429
.def(py::init<>())
2530
.def(
2631
"set_max_distance",
@@ -36,7 +41,13 @@ void define_factors(py::module& m) {
3641
)pbdoc");
3742

3843
// ICPFactor
39-
py::class_<ICPFactor>(m, "ICPFactor", "ICP per-point factor")
44+
py::class_<ICPFactor>(m, "ICPFactor", R"pbdoc(
45+
ICP per-point factor based on the conventional point-to-point distance.
46+
47+
References
48+
----------
49+
Zhang, "Iterative Point Matching for Registration of Free-Form Curve", IJCV1994
50+
)pbdoc")
4051
.def(py::init<>())
4152
.def(
4253
"linearize",
@@ -61,11 +72,11 @@ void define_factors(py::module& m) {
6172
py::arg("source_index"),
6273
py::arg("rejector"),
6374
R"pbdoc(
64-
Linearize the factor.
75+
Linearize the factor for the i-th source point.
6576
6677
Parameters
6778
----------
68-
target : PointCloud
79+
target : :class:`PointCloud`
6980
Target point cloud.
7081
source : PointCloud
7182
Source point cloud.
@@ -81,7 +92,7 @@ void define_factors(py::module& m) {
8192
Returns
8293
-------
8394
success: bool
84-
Success flag.
95+
Success flag. If false, the correspondence is rejected.
8596
H : numpy.ndarray
8697
Hessian matrix (6x6).
8798
b : numpy.ndarray
@@ -91,7 +102,13 @@ void define_factors(py::module& m) {
91102
)pbdoc");
92103

93104
// PointToPlaneICPFactor
94-
py::class_<PointToPlaneICPFactor>(m, "PointToPlaneICPFactor", "Point-to-plane ICP per-point factor")
105+
py::class_<PointToPlaneICPFactor>(m, "PointToPlaneICPFactor", R"pbdoc(
106+
Point-to-plane ICP per-point factor based on the point-to-plane distance.
107+
108+
References
109+
----------
110+
Zhang, "Iterative Point Matching for Registration of Free-Form Curve", IJCV1994
111+
)pbdoc")
95112
.def(py::init<>())
96113
.def(
97114
"linearize",
@@ -116,12 +133,12 @@ void define_factors(py::module& m) {
116133
py::arg("source_index"),
117134
py::arg("rejector"),
118135
R"pbdoc(
119-
Linearize the factor.
136+
Linearize the factor for the i-th source point.
120137
121138
Parameters
122139
----------
123140
target : PointCloud
124-
Target point cloud.
141+
Target point cloud. Must have normals.
125142
source : PointCloud
126143
Source point cloud.
127144
kdtree : KdTree
@@ -136,7 +153,7 @@ void define_factors(py::module& m) {
136153
Returns
137154
-------
138155
success: bool
139-
Success flag.
156+
Success flag. If false, the correspondence is rejected.
140157
H : numpy.ndarray
141158
Hessian matrix (6x6).
142159
b : numpy.ndarray
@@ -146,7 +163,13 @@ void define_factors(py::module& m) {
146163
)pbdoc");
147164

148165
// GICPFactor
149-
py::class_<GICPFactor>(m, "GICPFactor", "Generalized ICP per-point factor") //
166+
py::class_<GICPFactor>(m, "GICPFactor", R"pbdoc(
167+
Generalized ICP per-point factor based on distribution-to-distribution distance.
168+
169+
References
170+
----------
171+
Segal et al., "Generalized-ICP", RSS2005
172+
)pbdoc") //
150173
.def(py::init<>())
151174
.def(
152175
"linearize",
@@ -171,14 +194,14 @@ void define_factors(py::module& m) {
171194
py::arg("source_index"),
172195
py::arg("rejector"),
173196
R"pbdoc(
174-
Linearize the factor.
197+
Linearize the factor for the i-th source point.
175198
176199
Parameters
177200
----------
178201
target : PointCloud
179-
Target point cloud.
202+
Target point cloud. Must have covariances.
180203
source : PointCloud
181-
Source point cloud.
204+
Source point cloud. Must have covariances.
182205
kdtree : KdTree
183206
KdTree for the target point cloud.
184207
T : numpy.ndarray
@@ -191,7 +214,7 @@ void define_factors(py::module& m) {
191214
Returns
192215
-------
193216
success: bool
194-
Success flag.
217+
Success flag. If false, the correspondence is rejected.
195218
H : numpy.ndarray
196219
Hessian matrix (6x6).
197220
b : numpy.ndarray

‎src/python/kdtree.cpp

+10-10
Original file line numberDiff line numberDiff line change
@@ -37,11 +37,11 @@ void define_kdtree(py::module& m) {
3737
R"""(
3838
KdTree(points: numpy.ndarray, num_threads: int = 1)
3939
40-
Construct a KdTree from numpy.
40+
Construct a KdTree from a numpy array.
4141
4242
Parameters
4343
----------
44-
points : numpy.ndarray, shape (n, 3) or (n, 4)
44+
points : :class:`numpy.ndarray`, shape (n, 3) or (n, 4)
4545
The input point cloud.
4646
num_threads : int, optional
4747
The number of threads to use for KdTree construction. Default is 1.
@@ -54,11 +54,11 @@ void define_kdtree(py::module& m) {
5454
R"""(
5555
KdTree(points: PointCloud, num_threads: int = 1)
5656
57-
Construct a KdTree from a point cloud.
57+
Construct a KdTree from a small_gicp.PointCloud.
5858
5959
Parameters
6060
----------
61-
points : PointCloud
61+
points : :class:`PointCloud`
6262
The input point cloud.
6363
num_threads : int, optional
6464
The number of threads to use for KdTree construction. Default is 1.
@@ -86,7 +86,7 @@ void define_kdtree(py::module& m) {
8686
found : int
8787
Whether a neighbor was found (1 if found, 0 if not).
8888
k_index : int
89-
The index of the nearest neighbor in the point cloud.
89+
The index of the nearest neighbor in the point cloud. If a neighbor was not found, the index is -1.
9090
k_sq_dist : float
9191
The squared distance to the nearest neighbor.
9292
)""")
@@ -114,9 +114,9 @@ void define_kdtree(py::module& m) {
114114
Returns
115115
-------
116116
k_indices : numpy.ndarray, shape (k,)
117-
The indices of the k nearest neighbors in the point cloud.
117+
The indices of the k nearest neighbors in the point cloud. If a neighbor was not found, the index is -1.
118118
k_sq_dists : numpy.ndarray, shape (k,)
119-
The squared distances to the k nearest neighbors.
119+
The squared distances to the k nearest neighbors (Sorted in ascending order).
120120
)""")
121121

122122
.def(
@@ -155,7 +155,7 @@ void define_kdtree(py::module& m) {
155155
Returns
156156
-------
157157
k_indices : numpy.ndarray, shape (n,)
158-
The indices of the nearest neighbors for each input point.
158+
The indices of the nearest neighbors for each input point. If a neighbor was not found, the index is -1.
159159
k_sq_dists : numpy.ndarray, shape (n,)
160160
The squared distances to the nearest neighbors for each input point.
161161
)""")
@@ -201,8 +201,8 @@ void define_kdtree(py::module& m) {
201201
Returns
202202
-------
203203
k_indices : list of numpy.ndarray, shape (n,)
204-
The list of indices of the k nearest neighbors for each input point.
204+
The list of indices of the k nearest neighbors for each input point. If a neighbor was not found, the index is -1.
205205
k_sq_dists : list of numpy.ndarray, shape (n,)
206-
The list of squared distances to the k nearest neighbors for each input point.
206+
The list of squared distances to the k nearest neighbors for each input point (sorted in ascending order).
207207
)""");
208208
}

‎src/python/misc.cpp

+1-1
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,6 @@ void define_misc(py::module& m) {
2222
const auto points = read_ply(filename);
2323
return std::make_shared<PointCloud>(points);
2424
},
25-
"Read PLY file. This function can only read simple point clouds with XYZ properties for testing. Do not use this for general PLY IO.",
25+
"Read PLY file. This function can only read simple point clouds with XYZ properties for testing purposes. Do not use this for general PLY IO.",
2626
py::arg("filename"));
2727
}

‎src/python/pointcloud.cpp

+1-1
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ void define_pointcloud(py::module& m) {
4141
R"""(
4242
PointCloud(points: numpy.ndarray)
4343
44-
Construct a PointCloud from numpy.
44+
Construct a PointCloud from a numpy array.
4545
4646
Parameters
4747
----------

0 commit comments

Comments
 (0)