Add some documentation for Regular_triangulation::insert_if_in_star

[VincentRouvreau]

Please use the following template to help us managing pull requests.

Summary of Changes

There was no issue in the tracker, but Regular_triangulation::insert_if_in_star was not documented.

Release Management

• Affected package(s): Triangulation
• Feature/Small Feature (if any): https://cgal.geometryfactory.com/CGAL/Members/wiki/Features/Small_Features/Add_doc_for_RT::insert_if_in_star -- preapproved 2021-02-18
• Link to compiled documentation (obligatory for small feature) Triangulation
• License and copyright ownership: no change

[mglisse]

Would it be possible to get a different reviewer? While I did talk with Clément about some details at the time, I am not that familiar with this package, which was written by Samuel, Olivier and Clément (@cjamin also wrote the code in gudhi using those undocumented interfaces). I think Mael knows this code much better than I do... Actually, anyone familiar with the design of the 2D/3D code might be a suitable reviewer, to decide what should be a public interface or not.

[sloriot]

Sorry I thought you were using this code. No pb, I removed you.

[MaelRL]

Sorry for the delay, @VincentRouvreau.

Why do you think this should be documented? The function does not have an equivalent in Triangulation_23 so I was not familiar with it, and I find it a little awkward looking at the code: its idea is to insert the point only if the vertex star_center appears in the conflict zone of p during insertion... But in practice it is inserted anyway if:

• it increases the dimension of the triangulation;
• it's hidden (because if it's hidden, it is added to the cache of hidden points automatically).
• it's at the same geometrical position as an existing vertex, but its weight is greater;

One could argue point #1 is fine. Point #2 is a little surprising: the conflict zone is empty, so start_point is not in it, why is it being inserted anyway? Point #3 is just weird: the conflict zone is defined and it can be computed, yet it is ignored.

[mglisse]

The motivation for documenting it is that we are using it in Gudhi, and it is always a bit dangerous to depend on undocumented interfaces. This function is used in https://github.com/GUDHI/gudhi-devel/blob/c838e3ec441109cc02ea4612dd2189860662298f/src/Tangential_complex/include/gudhi/Tangential_complex.h#L1027 in the function compute_star. The goal of this function is to compute a subset of a regular triangulation, namely the star of some given point (which by construction cannot end up hidden). I didn't check the code, but you can imagine using the usual algorithm, but aborting an insertion if the created cells would not touch the center, so the triangulation does not grow too much. We could also remove some points that used to be close but are now separated from the center, but that looks like more work than it would save.
With this premise, it makes sense to me to insert points that increase the dimension (it is always in the star of all non-hidden existing points). Inserting it as a hidden point does seem strange, maybe Clément didn't find disabling that worth the trouble? For point 3, that's true, we don't need to insert it if the conflict zone does not contain the center. Maybe some original version was removing the non-adjacent vertices so this would always be the case? Or since it replaces an existing point, it does not increase the size of the triangulation and inserting it is not too bad? I didn't check the code, maybe the documentation can be weaker and say that if the point would not be in the star, its insertion may be skipped (but isn't always). Or if fixing 2 and 3 is easy...

[mglisse]

Looking at point 3, if we reinsert a point with exactly the same weight (why not ≤?), we don't insert, and then only if the dimension is 0 (so p is the same as star_center) we replace the only vertex with the new point (strange that is doesn't have an early out, it falls through to insert_in_conflicting_cell). In other cases it goes to insert_in_conflicting_cell which I think does check the conflict zone. No?

[MaelRL]

Looking at point 3, if we reinsert a point with exactly the same weight (why not ≤?), we don't insert, and then only if the dimension is 0 (so p is the same as star_center) we replace the only vertex with the new point (strange that is doesn't have an early out, it falls through to insert_in_conflicting_cell). In other cases it goes to insert_in_conflicting_cell which I think does check the conflict zone. No?

Right, I skimmed a little too fast over the dimension check. Point #2 could be just:

  [in insert_in_conflicting_cell()]
  ... 
  if (!in_conflict)
  {
+   if(only_if_this_vertex_is_in_the_cz == Vertex_handle())
      m_hidden_points.push_back(p);
    return Vertex_handle();
  }
  ...

but maybe it is not worth the behavior break?

[mglisse]

Yes, that change makes sense to me. For any behavior change we will have to test a bit in gudhi, but I don't see how this one could affect us.
Possibly with a few minor code changes as discussed, does it now seem reasonable to you to document this function? (at least the version with 2 arguments, which is the one we use)

[MaelRL]

Yes, that change makes sense to me. For any behavior change we will have to test a bit in gudhi, but I don't see how this one could affect us.

It is also unused in CGAL and the probability some third party is using that very specific undocumented function is relatively low.

Possibly with a few minor code changes as discussed, does it now seem reasonable to you to document this function? (at least the version with 2 arguments, which is the one we use)

Sure. There are just some sentences that I would rephrase in the doc, I will put it directly in suggestion in review of the PR.

[VincentRouvreau]

  [in insert_in_conflicting_cell()]
  ... 
  if (!in_conflict)
  {
+   if(only_if_this_vertex_is_in_the_cz == Vertex_handle())
      m_hidden_points.push_back(p);
    return Vertex_handle();
  }
  ...

but maybe it is not worth the behavior break?

I added your proposal on e511b68 and tested it. It seems it does not break our testing suites, neither some custom tests I performed.

[VincentRouvreau]

I am ok with your proposal. I took them as is.
@MaelRL and @mglisse tell me if it's ok for you.

[MaelRL]

/build:v0

[github-actions]

The documentation is built. It will be available, after a few minutes, here : https://cgal.github.io/5370/v0/Manual/index.html

[afabri]

@VincentRouvreau can you remove the trailing whitespace reported in the check

[maxGimeno]

Successfully tested in https://cgal.geometryfactory.com/CGAL/testsuite/results-5.3-Ic-78.shtml

[lrineau]

The small feature corresponding to this PR is accepted. It has a modification to CHANGES.md but this PR does not. I cannot merge this PR as it is. Please change the CHANGES.md in accordance with the small feature.

[VincentRouvreau]

The small feature corresponding to this PR is accepted. It has a modification to CHANGES.md but this PR does not. I cannot merge this PR as it is. Please change the CHANGES.md in accordance with the small feature.

Should be ok with eb04a9b and 28932cd