Add ClipPlaneSet method to clip a generic CurveVector

[dassaf4]

For imodel02 (connectors).

Tasks

Beta Give feedback

1. implement on imodel-native
2. port to imodel02
3. port to PowerPlatform
4. port to iTwin (if there doesn't already exist a clip method that takes AnyCurve)

[dassaf4]

Details:

• When the input CurveVector is a closed region, we already have ClipPlaneSet::ClipPlanarRegion. Given a region input, it returns a single region output.
• When the input CurveVector is open, the result can be multiple (disjoint) CurveVectors. What is the preferred return type for this?
  • I've seen disjoint curves packaged into one CurveVectorPtr that has BOUNDARY_TYPE_None, however the doc for this enum type discourages this, preferring instead bvector<CurveVectorPtr>. This kind of rules out one method for both open and closed inputs, unless we want to return the single closed result as the only entry in the bvector, which I guess could work. But at the very least, it means a new method, because we cannot change the signature of the existing one.
  • The problem with returning a CurveVectorPtr per clipped open curve piece is that there is no record of the provenance of that piece in the context of the original open curve, e.g., the fractional parameter span of the clipped piece in the original curve's [0,1] parameter space. This is why I like CurveLocationDetailPair, an array of which is returned by ClipPlaneSet::AppendCrossings---each entry in this array describes a pair of locations on the input curve representing the start and end of a clipped piece. If you have such an array, you can easily build up a bvector of the clipped pieces by calling CurveVector::CloneBetweenDirectedFractions(detail0, detail1) on each CurveLocationDetailPair.
• When the input CurveVector is open, we also have the option to ignore certain ClipPlanes in the clipper. I believe there are a couple of flags on the clipper (or clip plane) that determine this. There should be methods on ClipPlane that return visibility flags or some such. At the least, we should honor plane visibility and skip those that are hidden/invisible. We could also provide an input flag to ignore them and clip to all planes. Again, look for precedent in the API.
• So I propose two new methods:
  • Main method: void ClipCurveVector(CurveVectorCR curve, bvector<CurveVectorPtr>& clippedCurves) const calls the existing ClipPlanarRegion method if CurveVector::IsAnyRegionType() is true, otherwise the new open method (below).
  • Open method: bool ClipOpenPath(CurveVectorCR openCurve, bvector<CurveVectorPtr>* pClippedCurves = nullptr, bvector<CurveLocationDetailPair>* pClippedDetails = nullptr) const. Both optional returned arrays should be sorted by the original open path's global parameterization, or if boundaryType None, by the ordering of its primitives. Return false if openCurve.IsAnyRegionType() returns true; otherwise, calls AppendCrossings + CloneBetweenDirectedFractions as described above. Note: this method should handle input of non-region boundaryType, i.e., Open or None.

[saeeedtorabi]

In imodel-native, there's a variant of CloneBetweenDirectedFractions which takes curve details. I should add that when I do the port to MS.

[saeeedtorabi]

imodel-native PR
#353 (merged)

imodel02 PR
https://dev.azure.com/bentleycs/iModelTechnologies/_git/imodel02/pullrequest/351921 (merged)
https://dev.azure.com/bentleycs/iModelTechnologies/_git/imodel02/pullrequest/352640 (merged)

power-platform PR and PBI
https://dev.azure.com/bentleycs/PowerPlatform/_workitems/edit/1238279
https://dev.azure.com/bentleycs/PowerPlatform/_git/PPBase/pullrequest/351920 (merged)

iTwin PR
iTwin/itwinjs-core#5804