[polygon] tutorial done and library ready for release
I have just added a tutorial to the documentation. The tutorial walks the reader through the requirements, design and implementation of a toy layout versus schematic comparision application. I would like feedback from the community on whether this is what you are looking for in a tutorial. Also I'd like to check with my review manager, Fernando, if this tutorial satisfies the acceptance requirement that I add a tutorial to the documentation. The tutorial can be found here: https://svn.boost.org/svn/boost/sandbox/gtl/doc/gtl_tutorial.htm At this stage I think I have satisfied the acceptance requirements from the review and would like to coordinate merging the library onto the trunk and release branch to get into the next release of boost. A little guidance from the release manager would be appreciated. Thanks, Luke
On Fri, May 21, 2010 at 2:14 PM, Simonson, Lucanus J <lucanus.j.simonson@intel.com> wrote:
I have just added a tutorial to the documentation. The tutorial walks the reader through the requirements, design and implementation of a toy layout versus schematic comparision application. I would like feedback from the community on whether this is what you are looking for in a tutorial. Also I'd like to check with my review manager, Fernando, if this tutorial satisfies the acceptance requirement that I add a tutorial to the documentation. The tutorial can be found here: https://svn.boost.org/svn/boost/sandbox/gtl/doc/gtl_tutorial.htm
At this stage I think I have satisfied the acceptance requirements from the review and would like to coordinate merging the library onto the trunk and release branch to get into the next release of boost. A little guidance from the release manager would be appreciated.
The steps would be something like this: * Wait a couple of days to see if you get any further feedback. Perfection isn't required, but it would be nice if there aren't any really major issues. * Take a look at the "New Library Checklist" on https://svn.boost.org/trac/boost/wiki/ReleasePractices/ManagerCheckList. As long as you are fairly close to meeting it, go ahead and commit to trunk. * Watch the regression tests as they cycle on different platforms. In the meantime, address any missing pieces on the checklist. * Once tests are either passing or the reason for failures understood and being addressed, and the New Library Checklist seems to be covered, ask the release managers for permission to commit to branches/release. --Beman
Beman Dawes wrote:
* root/index.html includes the library in its list of new libraries. * root/libs/libraries.htm entry is OK, both in the alphabetic list and in the category lists. * root/libs/maintainers.txt entry is OK. * website/public_html/beta/feed/history/ entry is OK. * The library has been added to the website documentation list Am I expected to do these items or is the maintainer of the boost website going to do them? * The library's root/libs/xxx directory contains an index.html file with either the main docs or a redirection to the main docs. I tried to commit to trunk but got a 403 Forbidden error. Can someone please grant me write access to trunk? * The primary docs pages meet Boost requirements and guidelines. Don't leave this until too late; it has turned up lots of issues in the past. There were no issues with this flagged during the review, but I have added the copyright notice to all html files since the review after revisiting the guidelines. * Component has been added to Trac. See https://svn.boost.org/trac/boost/admin/ticket/components How do I get a login to trac so that I can add the component? * Trunk inspection report is clean. * Trunk regression tests are reasonably clean or marked up. Where do these reports get posted so that I know how to check them? I have run the inspect tool on my code today and cleaned up the errors that crept in since last time. Thanks, Luke
On 5/24/2010 3:54 PM, Simonson, Lucanus J wrote:
You will have to ask for access directly (see the link below for whom to ask).
To get an svn + trac login.. <https://svn.boost.org/trac/boost#GettingaTracSVNUserid>. And once you have that, ask here again and one of the trac admins will add the component. Make sure to mention your trac user ID at that time so we can assign it to the component.
Once your lib is in trunk, they will show up in the trunk regression testing pages <http://www.boost.org/development/testing.html>. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org (msn) - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim,yahoo,skype,efnet,gmail
On 24 May 2010 21:54, Simonson, Lucanus J <lucanus.j.simonson@intel.com> wrote:
You can do these (once you've got commit access). Although Beman or I usually deal with the root file.
* website/public_html/beta/feed/history/ entry is OK. * The library has been added to the website documentation list
I normally do these based on your libraries.htm entry. Although if you're interested the relevant files are at: http://svn.boost.org/svn/boost/website/public_html/beta/doc/libraries.xml http://svn.boost.org/svn/boost/website/public_html/beta/feed/history/boost_1...
* The library's root/libs/xxx directory contains an index.html file with either the main docs or a redirection to the main docs.
I tried to commit to trunk but got a 403 Forbidden error. Can someone please grant me write access to trunk?
If you don't get a response, I think you need to ask the moderators (boost-owner@lists.boost.org).
* The primary docs pages meet Boost requirements and guidelines. Don't leave this until too late; it has turned up lots of issues in the past.
There were no issues with this flagged during the review, but I have added the copyright notice to all html files since the review after revisiting the guidelines.
I sometimes have a few suggestions that aren't really relevant for the review. IIRC the html will need to be tidied up a bit to work on the website. It'd also be better if it used a CSS based layout rather than a table layout, if you want I could prepare a template for that, what software do you use to write your html? I'll look at the documentation in more detail later.
* Component has been added to Trac. See https://svn.boost.org/trac/boost/admin/ticket/components
How do I get a login to trac so that I can add the component?
You log in to trac using your subversion details. But you need to ask someone to add the component. Starting a new thread with '[trac]' in the subject usually seems to work.
Daniel James wrote:
I used frontpage. I'm willing to work with you to make the html work better with the boost website. What I did with the tables makes maintenance somewhat a pain, so if you can help me implement it a better way I'll be happy to do my part and actually use the better way. Thanks, Luke
On 24 May 2010 22:37, Simonson, Lucanus J <lucanus.j.simonson@intel.com> wrote:
I used frontpage. I'm willing to work with you to make the html work better with the boost website. What I did with the tables makes maintenance somewhat a pain, so if you can help me implement it a better way I'll be happy to do my part and actually use the better way.
I'm afraid I don't know frontpage. Was it a pain because you had to update the contents on all the pages, or because tables make editing awkward? I'll post a css based version of one of your pages in the next couple of days to show you what I'm thinking. This isn't a high priority, we can sort these things out later in the release. Right now, it's more important that you get the code integrated into the testing system. Daniel
Daniel James wrote:
I did the libraries.htm and maintainers.txt. I left the root/index.html alone for now.
I would prefer you do it.
I have the library fully checked in now including the index.html in root/libs/polygon
I still don't have a coponent in trac as far as I know. I am able to log into trac now.
So far my library is showing up in the inspect report but not the regression testing report. What triggers the regression testing to pick up a new library? Thanks, Luke
On 6/2/2010 10:59 AM, Simonson, Lucanus J wrote:
You have one now.. I'm assuming your Trac ID is "ljsimmons". Please fill in your full name and email in Trac if you haven't done so. If you give me a short description of the lib I can add it to the Trac listings of the components <https://svn.boost.org/trac/boost/report/15>.
Did you add your library to the "trunk/status/Jamfile.v2"? -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org (msn) - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim,yahoo,skype,efnet,gmail
On 2 June 2010 18:20, Simonson, Lucanus J <lucanus.j.simonson@intel.com> wrote:
Not really, since it's the release managers checklist. If anyone fancies writing a guide for preparing new libraries for release, it shouldn't be too much work to edit all of this information into a reasonable form and put it on the wiki. Daniel
Daniel James wrote:
Who is the release manager right now? It looks like Steven Watanabe ran my library's test with the como compiler, but still nothing from the other testers. Steven, did you manually run the test? I'm still a little in the dark about what is going on with the regression tests wrt my library. Thanks, Luke
AMDG Simonson, Lucanus J wrote:
It looks like Steven Watanabe ran my library's test with the como compiler, but still nothing from the other testers. Steven, did you manually run the test? I'm still a little in the dark about what is going on with the regression tests wrt my library.
Look at the revision for each tester. I started a run for just your library immediately after I committed the fix. None of the other testers have run since then. In Christ, Steven Watanabe
Simonson, Lucanus J wrote:
Who is the release manager right now?
At the end of <http://www.boost.org/users/news/version_1_43_0>, we have the following Acknowledgements Beman Dawes, Eric Niebler, Rene Rivera, Daniel James and Vladimir Prus managed this release. The same can also be found in the 1.42 release notes. So we can conclude that "The Boost Release Managers" refers to this group of 5 people. Regards, Thomas
AMDG Simonson, Lucanus J wrote:
I still don't see me regression tests running. As far as I know I have done everything needful. Can someone take a look?
The tests end up in the wrong build directory because you used Jamroot in libs/polygon. I just fixed this. In Christ, Steven Watanabe
Beman Dawes wrote:
[snip details from Beman] [reference other details listed in various replies in this thread] Is all of this information in one place, in a handy checklist-plus-details format so other new contributors know what to do in the future? It would be better to point folks to such a list in the future. _____ Rob Stewart robert.stewart@sig.com Software Engineer, Core Software using std::disclaimer; Susquehanna International Group, LLP http://www.sig.com IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.
On 25 May 2010 12:20, Stewart, Robert <Robert.Stewart@sig.com> wrote:
Is all of this information in one place, in a handy checklist-plus-details format so other new contributors know what to do in the future? It would be better to point folks to such a list in the future.
There's this incomplete page: https://svn.boost.org/trac/boost/wiki/DeveloperChecklist There's also this very out of date page: https://svn.boost.org/trac/boost/wiki/ReleasePractices/Procedures Daniel
On Fri, May 21, 2010 at 11:14 AM, Simonson, Lucanus J <lucanus.j.simonson@intel.com> wrote:
I have just added a tutorial to the documentation. The tutorial walks the reader through the requirements, design and implementation of a toy layout versus schematic comparision application. I would like feedback from the community on whether this is what you are looking for in a tutorial. Also I'd like to check with my review manager, Fernando, if this tutorial satisfies the acceptance requirement that I add a tutorial to the documentation. The tutorial can be found here: https://svn.boost.org/svn/boost/sandbox/gtl/doc/gtl_tutorial.htm
At this stage I think I have satisfied the acceptance requirements from the review and would like to coordinate merging the library onto the trunk and release branch to get into the next release of boost. A little guidance from the release manager would be appreciated.
I just took a look at this having some interest in using the polygon library as a user. Please take these first impressions with a grain of salt because I didn't participate in the review. That said here's some of my thoughts (unfiltered): * You use quite a lot of jargon that's specific to the chip design field. I'm not sure if normal C++ developers are your target audience, but a tutorial on how to do VLSI layout might not be the best. If you still really want to use that domain, then you might as well explain a few things before you start diving into the rationale of why you'd want to check your chip layouts using a program. * I understand that there are already industry standards when it comes to chip layout and other things, however I find just the normal problems with polygons solved easily would be a huge and powerful tutorial. Things like what the minimum dimensions should be for a set of smaller polygons to be contained in a single rectangle (minimization problem, maybe for the garment industry) or the maximum number of triangles of a given dimension can be fit in a given polygon (maximization problem, maybe for the construction industry). Naive question: does it have to be specific to VLSI chip design or did it just come out in the review? * Given that I don't see where this tutorial fits in the whole scheme of documentation, this tutorial seems to rely on a lot of missing context. Is that intentional by virtue of placement, or is this supposed to be a stand-alone tutorial? I haven't really dug into the details of the tutorial and I'll trust the experts when it comes to the details of the solution. However, I think it would be powerful to show how the library can be used for "normal" everyday and considerably non-trivial problems that are made trivial by the library. Thanks and I hope this helps! -- Dean Michael Berris deanberris.com
Dean Michael Berris wrote:
If by "it" you mean usage of the library, then no. The library generally handles polygons with integer coordinates. I'm not sure either of your suggestions turns out to be easy using the library. You are suggesting difficult things in their own right that would make good extensions to a geometry library.
My intention was that the tutorial be self contained and that the documentation should help the reader understand the usage of the library in the tutorial.
It does help. I was concerned that the tutorial would be unapproachable for people not familiar with the VLSI domain. Suggestions on a simpler tutorial would be helpful. Thanks, Luke
On Tue, May 25, 2010 at 12:31 AM, Simonson, Lucanus J <lucanus.j.simonson@intel.com> wrote:
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. ;)
I'm not sure either of your suggestions turns out to be easy using the library. You are suggesting difficult things in their own right that would make good extensions to a geometry library.
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. ;)
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?
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.
Thanks,
Glad to be able to help. :) -- Dean Michael Berris deanberris.com
Dean Michael Berris wrote: <snip>
<snip>
<snip>
<snip>
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
On Wed, May 26, 2010 at 2:31 AM, Simonson, Lucanus J <lucanus.j.simonson@intel.com> wrote:
[snip code] Unfortunately no, but it would be good to make a tutorial that has starts with these simple problems, and works its way up to... [snip]
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.
.. the convex hull implementation using Boost.Geometry.
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.
It's just me though, I'm not sure if others are having any problems with the current tutorial. ;)
Thanks for taking the time to look at the tutorial,
You're welcome. Have a great day! -- Dean Michael Berris deanberris.com
Dean Michael Berris wrote:
I think you have a good point that the tutorial should be something really interesting to show the power of the library. To that end I implemented today Minkowski sum of two polygon sets. Minkowski sum of two polygon sets is a generalization of Minkowski sum of two polygons. In the code I call it convolution of two polygon sets. If you look at the API of the library I provide convolve(point, point), convolve(polygon, point) and convolve(rectangle, rectangle). Using the attached code I could provide convolve(polygon, polygon), convolve(polygon_set, polygon) and convolve(polygon set, polygon set). I didn't comment the code to explain the intuition behind the algorithm, but there isn't much code there, just 82 lines for the implementation itself, so it should make for a nice short tutorial complete with pictures and detailed explanation of what minkowski sums are and how my algorithm and the implementation of it work. Does solving this problem meet your expectations for a good tutorial for the library? Regards, Luke
Hi Luc, While I agree with Dean about the current tutorials being perhaps too domain-specific, I do find that they give a good overall sense of the library, specially in combination with the examples. Would I would do to complete the "overview" picture is "annotate" the examples. That is, they do contains a few remarks, but IMO thet could use longer comments explaning rather than just restating what the code is doing. For example.. from Point Usage: //constructing a gtl point typedef gtl::point_data<int> Point; int x = 10; int y = 20; Point pt(x, y); assert(gtl::x(pt) == 10); assert(gtl::y(pt) == 20); There it could say that point_data<> is one particular model provided by the library BUT that the library is designed to be completely generic, so that could just as well have been a user defined type properly "adapted" //a quick primer in isotropic point access typedef gtl::orientation_2d O; using gtl::HORIZONTAL; using gtl::VERTICAL; O o = HORIZONTAL; assert(gtl::x(pt) == gtl::get(pt, o)); Here it could say a few words about why isotropic access is useful and why it is part of the library API. And so on with all the examples. Having said, as a review manager, I believe the library is ready to be released. Best Fernando Cacciola
participants (9)
-
Beman Dawes -
Daniel James -
Dean Michael Berris -
Fernando Cacciola -
Rene Rivera -
Simonson, Lucanus J -
Steven Watanabe -
Stewart, Robert -
Thomas Klimpel