search

mapbox / polylabel

A fast algorithm for finding the pole of inaccessibility of a polygon (in JavaScript and C++)
Other
1.44k stars 151 forks source link

Added polylabel article, updated README #76

Open hollasch opened 3 years ago

hollasch commented 3 years ago

Article copied from the original post on the Mapbox blog: https://blog.mapbox.com/a-new-algorithm-for-finding-a-visual-center-of-a-polygon-7c77e6492fbc This includes a new directory, images/, to hold the article figures. Some very light editing has also been done.

Also updated the project README to reference the article. Cleaned up the formatting a bit to be useable in plaintext form.

hollasch commented 3 years ago

Forgot to mention that the article was converted to Markdeep, which is a Markdown-like super-variant that loads and browses just like a regular HTML file, but supports a lot of extra features. This includes the ability to freely style the article with standard CSS — I've just used the default styling for this submission.

mourner commented 3 years ago

Thanks for the PR! However you haven't indicated in the description why the article needs to be copied to the repo. Anything in particular that prompted this?

hollasch commented 3 years ago

Yeah, I should really have created an issue first to get your feedback, but oh well. Don't feel like you need to take this.

My thinking is that the article is nowhere mentioned in the project or its README, and the project would greatly benefit from the additional explanation. I also decided to include the article to make it easy for users to reference it directly out of their clones as a local resource.

Finally, in going through it this weekend, I feel that there are pieces that could use more explanation or documentation. For example, I reverse-engineered the point-segment distance function to find it's just doing a projection of the point onto the line containing the segment to get a ray t parameter — that could use more explanation, but it's not huge.

More mysterious is the inside flag toggling equation, and what that's actually doing. Nowhere in the code is the input polygon explained, but it looks like a polygon is a set of rings, in arbitrary order, with arbitrary vertex winding order, and where the interior test is purely driven by edge-crossing count. I'm still puzzling out the inside/outside flag tracking.

All this to say that as people who use the library feed back aspects that could use more explanation, you could add these comments to a wiki, or the README, or code comments, or some combination, but the blog post that really provides the overview is read-only and static. Moving it into the project allows the approach to refine or evolve, and hosts a more "living document" approach than a now four-year-old article.

In the end, I just figured I'd sketch out a PR as much as a question as a something you might accept. I maintain open source myself, so you won't hurt my feelings at all if you decide to table this for now.

hollasch commented 3 years ago

Oh — I should also mention that I'm playing with a spheroidal approach, using either cubic or icosohedral subdivision of the sphere. If it's fruitful, it would be good to augment this project.

And another final thought is that the documentation in the project needn't be a verbatim copy of the blog article, though it would look very much like it.

TWiStErRob commented 3 years ago

Have you considered a /docs folder or gh-pages branch? There's already a lot of files in the root directory.

hollasch commented 3 years ago

Absolutely. You could certainly consider this an increment to a web-hosted project page. Trying small bites. :)

hollasch commented 3 years ago

BTW, I can do the set up for site hosting if that's interesting to you. I'm one of the admins on the Ray Tracing in One Weekend site, so am very familiar with the process.