From e86003c5c65fa09300a3fed878e1658a8ddf81cb Mon Sep 17 00:00:00 2001 From: Simon Giraudot Date: Wed, 7 Oct 2020 11:06:32 +0200 Subject: [PATCH] Reference manual --- .../PackageDescription.txt | 2 +- .../orient_scanlines_example.cpp | 1 - .../include/CGAL/scanline_orient_normals.h | 91 +++++++++++++++++++ 3 files changed, 92 insertions(+), 2 deletions(-) diff --git a/Point_set_processing_3/doc/Point_set_processing_3/PackageDescription.txt b/Point_set_processing_3/doc/Point_set_processing_3/PackageDescription.txt index 3d482fdc4f2..32e0e9f61c2 100644 --- a/Point_set_processing_3/doc/Point_set_processing_3/PackageDescription.txt +++ b/Point_set_processing_3/doc/Point_set_processing_3/PackageDescription.txt @@ -66,6 +66,7 @@ format. - `CGAL::jet_estimate_normals()` - `CGAL::pca_estimate_normals()` - `CGAL::mst_orient_normals()` +- `CGAL::scanline_orient_normals()` - `CGAL::edge_aware_upsample_point_set()` - `CGAL::compute_vcm()` - `CGAL::vcm_estimate_normals()` @@ -101,4 +102,3 @@ format. - `CGAL::make_las_point_writer()` */ - diff --git a/Point_set_processing_3/examples/Point_set_processing_3/orient_scanlines_example.cpp b/Point_set_processing_3/examples/Point_set_processing_3/orient_scanlines_example.cpp index 3d6b7fb8cb2..bb28ef809e0 100644 --- a/Point_set_processing_3/examples/Point_set_processing_3/orient_scanlines_example.cpp +++ b/Point_set_processing_3/examples/Point_set_processing_3/orient_scanlines_example.cpp @@ -45,7 +45,6 @@ int main (int argc, char** argv) return EXIT_FAILURE; } - points.resize(100000); std::cerr << "Estimating normals" << std::endl; CGAL::jet_estimate_normals diff --git a/Point_set_processing_3/include/CGAL/scanline_orient_normals.h b/Point_set_processing_3/include/CGAL/scanline_orient_normals.h index d092701ddce..04a08569711 100644 --- a/Point_set_processing_3/include/CGAL/scanline_orient_normals.h +++ b/Point_set_processing_3/include/CGAL/scanline_orient_normals.h @@ -219,6 +219,97 @@ void orient_scanline (Iterator begin, Iterator end, // Public section // ---------------------------------------------------------------------------- +/** + \ingroup PkgPointSetProcessing3Algorithms + + Orients the normals of the range of `points` by estimating a line + of sight and checking its consistency with the current normal orientation. + + \warning this function requires the input `points` to be ordered + along scanlines aligned on the XY-plane. It is typically designed + for 2.5D urban datasets acquired through, for example, airborne + LIDAR devices. + + First, scanlines are estimated as subranges of `points` by + iterating on `points`: + + - if the named parameter `scan_direction_flag` is provided, the + range is cutted everytime the flag (which tells if the scanner + was moving in the positive or negative direction) changes. + + - if no direction flag map is provided, a fallback method simply + cuts the range everytime 3 consecutive points form an acute angle + on the projected XY-plane. This fallback method gives suboptimal + results. + + Then, the line of sight (estimated vector between a point and the + position of the scanner at its time of acquisition) is estimated: + + - if both `scan_direction_flag` and `scan_angle` are provided, the + line of sight can be directly computed as a combination of the 2D + vector of the projected scanline, the vertical vector and the + scan angle. + + - if only `scan_angle` is provided, then for each scanline, the + position of the scanner is estimated as being above the point of + the scanline which has the minimum scan angle absolute + value. This method is less optimal than the one using + `scan_direction_flag`. + + - if none of these property maps are provided, then for each + scanline, the position of the scanner is estimated as being above + of the barycenter of the points of the scanline projected on the + XY-plane. This fallback method gives suboptimal results. + + Once the line of sight is estimated for each point, the normals are + oriented by checking if, for one each, the line of sight and the + normal vector give a positive scalar product. If they don't, then + the normal vector is inverted. + + \note this method gives optimal results when `scan_direction_flag` + and `scan_angle` are provided. Correct results may still be + produced in the absence of either one or both of these properties, + as long as the point set is ordered in 2.5D scanlines. + + \tparam PointRange is a model of `Range`. The value type of + its iterator is the key type of the named parameter `point_map`. + + \param points input point range. + \param np an optional sequence of \ref bgl_namedparameters "Named Parameters" among the ones listed below + + \cgalNamedParamsBegin + \cgalParamNBegin{point_map} + \cgalParamDescription{a property map associating points to the elements of the point set `points`} + \cgalParamType{a model of `ReadablePropertyMap` whose key type is the value type + of the iterator of `PointRange` and whose value type is `geom_traits::Point_3`} + \cgalParamDefault{`CGAL::Identity_property_map`} + \cgalParamNEnd + + \cgalParamNBegin{normal_map} + \cgalParamDescription{a property map associating normals to the elements of the point set `points`} + \cgalParamType{a model of `WritablePropertyMap` whose key type is the value type + of the iterator of `PointRange` and whose value type is `geom_traits::Vector_3`} + \cgalParamNEnd + + \cgalParamNBegin{scan_angle_map} + \cgalParamDescription{a property map associating the angle of acquisition to the elements of the point set `points`} + \cgalParamType{a model of `ReadablePropertyMap` whose key type is the value type + of the iterator of `PointRange` and whose value type is `float`} + \cgalParamNEnd + + \cgalParamNBegin{scan_direction_flag} + \cgalParamDescription{a property map associating a flag describing the direction of the acquisition to the elements of the point set `points`} + \cgalParamType{a model of `ReadablePropertyMap` whose key type is the value type + of the iterator of `PointRange` and whose value type is `unsigned char`} + \cgalParamNEnd + + \cgalParamNBegin{geom_traits} + \cgalParamDescription{an instance of a geometric traits class} + \cgalParamType{a model of `Kernel`} + \cgalParamDefault{a \cgal Kernel deduced from the point type, using `CGAL::Kernel_traits`} + \cgalParamNEnd + \cgalNamedParamsEnd +*/ template void scanline_orient_normals (PointRange& points, const NamedParameters& np) {