I’m confused about the clip API. Could the operations be more clearly documented?

[wlinna]

Hello, I'm trying to understand how BooleanOps::clip works.

Clip a 1-D geometry with self. Returns the portion of ls that lies within self (known as the set-theoeretic intersection) if invert is false, and the difference (ls - self) otherwise.

This doesn't explain much to someone who doesn't already know what it does. For example, if I wanted to clip with an exterior of a Polygon, do I need to somehow convert it to a 1-D geometry first? If so, how is it done? How is a 1-D geometry represented and interpreted in georust?

I tried searching the Internet with "Clip a 1-D geometry", but all I get is a link back to georust docs.

I read from Discord that it's difficult to write documentation that provides complex information while making it easy to understand, and I can understand that. In that case an example might help, or a link to additional reading?

Thanks

[michaelkirk]

I wanted to clip with an exterior of a Polygon

Sorry, I'm not sure what you mean by this.

But maybe it's helpful to clarify that "1-D geometry" is reinforcing the type signature of the method - it means it takes a LineString as input.

[wlinna]

Thanks for the quick response.

if I wanted to clip with an exterior of a Polygon Sorry, I'm not sure what you mean by this.

Say I have Polygons A and B. I was thinking of using Polygon::exterior of B, wrap it in a MultiLineString and call something like A.clip(&b_exterior_multilinestr, ...). Would that make sense?

But maybe it's helpful to clarify that "1-D geometry" is reinforcing the type signature of the method - it means it takes a LineString as input.

ls is actually a MultiLineString. Is that also a 1-D geometry? If so, is a Polygon with an interior a 2-D geometry?

[wlinna]

No wait.. it's 1-D because it doesn't have thickness or any notion of solidity? (And thus only one coordinate is needed to specify a point in it.. though I'm not entirely sure how that'd work for a MultiLineString)

[michaelkirk]

No wait.. it's 1-D because it doesn't have thickness or any notion of solidity?

Exactly.

0-D: Point 1-D: Line/LineString/MultiLineString 2-D: Polygon/MultiPolygon/Rect/Triangle

I was thinking of using Polygon::exterior of B, wrap it in a MultiLineString and call something like A.clip(&b_exterior_multilinestr, ...). Would that make sense?

Maybe? It depends on what you are expecting to happen. Polygon::exterior is 1-dimensional.

So A.clip(&b_exterior_multilinestr, ...) will give you a 1 dimensional clipping - potentially a bunch of disparate line strings.

If that's what you are looking for, then great.

My guess though, is that you are looking for 2-dimensional clipping. Something like https://docs.rs/geo/latest/geo/algorithm/bool_ops/trait.BooleanOps.html

[wlinna]

Okay, thank you, this conversation has been very helpful

So A.clip(&b_exterior_multilinestr, ...) will give you a 1 dimensional clipping - potentially a bunch of disparate line strings. If that's what you are looking for than great.

Yes, that's exactly what I was looking for.

My guess though, is that you are looking for 2-dimensional clipping. I use those too, and I use them too.

Funnily enough, I find them intuitive as they are. Possibly because they are just simple type signatures (and because they are very common set operations)

I feel that I would have understood clip too if Clip a 1-D geometry with self was removed from the docstring. The reason is that I don't expect free-form comments to tell me something that the type signature does perfectly adequately. At least to me it seems clear that LineStrings in itself is different from Polygons for example. So the sentence made me overthink and question what I could see in the signature. I don't feel that Clip a 1-D geometry with self adds anything that the signature and the next sentence doesn't already express.

That might be just me though

[michaelkirk]

Thanks for explaining. Feel free to open a pull request if you think you can improve the documentation.