Re: [boost] [polygon] tutorial done and library ready for release

Subject: Re: [boost] [polygon] tutorial done and library ready for release
From: Simonson, Lucanus J (lucanus.j.simonson_at_[hidden])
Date: 2010-05-25 14:31:29

Dean Michael Berris wrote:
<snip>
> No, I meant "it" being the tutorial. I get that the geometry library
> is supposed to be generic but it doesn't seem so generic when (forgive
> me for pointing out) you and the company you work with is in the chip
> design/manufacturing business offer a tutorial which best fits that
> specific use case. ;)
> 
<snip>
> 
> Okay, so this is only for integer-coordinate based polygons... But
> there are a lot of algorithms that fall under the field of geometry
> like area, perimeter, center of gravity, etc. that can be used to
> illustrate the power of the library, right? I primarily would like to
> get a better idea of these algorithms that are available and usable
> "right away" with minimum effort. The tutorial I read didn't do that
> because, well, I think the area you chose to demonstrate the library
> is a little... well... contrived. ;)
> 
<snip>
> 
> Oh, okay. I think there is a disconnect between what your intention is
> and what is actually in the tutorial. I think I'm just missing a lot
> of context to better understand how to really use the library. The
> example in the tutorial was just too complex (necessarily so I think
> to demonstrate the power of the library) but I'm missing the simple
> utilities that I want to be able to use as a normal non-chip-designing
> C++ developer having to deal with simple polygon problems.
> 
> Would a tutorial like that be at all possible to write?
> 
<snip>
> 
> How about the simple problems like finding out whether two lines
> intersect, the resulting area of the union of two or more polygons, or
> maybe the convex hull problem? Those would really be interesting
> problems to illustrate solving using your library and would generally
> be more suitable to demo how to use and leverage the data structures
> and algorithms in the library.

Did you read the example code named polygon usage https://svn.boost.org/svn/boost/sandbox/gtl/doc/gtl_polygon_usage.htm and polygon set usage https://svn.boost.org/svn/boost/sandbox/gtl/doc/gtl_polygon_set_usage.htm?

    //now lets see what we can do with this polygon
    assert(gtl::area(poly) == 100.0f);
    assert(gtl::contains(poly, gtl::construct<Point>(5, 5)));
    assert(!gtl::contains(poly, gtl::construct<Point>(15, 5)));
    gtl::rectangle_data<int> rect;
    assert(gtl::extents(rect, poly)); //get bounding box of poly
    assert(gtl::equivalence(rect, poly)); //hey, that's slick
    assert(gtl::winding(poly) == gtl::COUNTERCLOCKWISE);
    assert(gtl::perimeter(poly) == 40.0f);

    //add 5 to all coords of poly
    gtl::convolve(poly, gtl::construct<Point>(5, 5));
    //multiply all coords of poly by 2
    gtl::scale_up(poly, 2);
    gtl::set_points(rect, gtl::point_data<int>(10, 10),
    gtl::point_data<int>(30, 30));
    assert(gtl::equivalence(poly, rect));

Here I show how to get the area of a polygon, the winding orientation of a polygon, the perimeter of a polygon, check if a polygon contains a point, get the bounding box (envelope) of a polygon, translate a polygon by convolving it with a point and scale a polygon.

    //now lets do something interesting
    PolygonSet ps2;
    ps2 += rectangle_data<int>(5, 5, 15, 15);
    PolygonSet ps3;
    assign(ps3, ps * ps2); //woah, I just felt the room flex around me
    PolygonSet ps4;
    ps4 += ps + ps2;
    
    //assert that area of result is equal to sum of areas
    //of input geometry minus the area of overlap between inputs
    assert(area(ps4) == area(ps) + area(ps2) - area(ps3));

Here I am getting the resulting area of the union of two or more polygons....

Convex hull would be a feature I could add to the library, and I could certainly write a document describing how I implemented it, however I don't plan on implementing it and would refer people to the boost.geometry implementation of that algorithm.

Since it is clear that people would prefer a simpler tutorial with no domain specific slant I'll write an additional tutorial demonstrating some different features of the library.

Thanks for taking the time to look at the tutorial,
Luke