Pages

Monday 30 May 2011

Open Layers 2.10 Beginners Guide

Thanks to Cameron Shorter for putting me in touch with packt publishing so I could review the new Open Layers book. This is a great chance for me to look at Open Layers as it is not something I get to use professionally as I usually live on the other end of the stack.

Summary since you are unlikely to review a full book review:

  • Great introduction to Open Layers by Erik Hazzard
  • Around $45 on Amazon
  • Available from Packt Publishing for a bit cheaper.
  • There is a sample chapter available.
  • James Fee Review
  • Geoweb Guru Review
  • Review - How well does the book address these issues:
    • Typesetting: Paper (8/10), PDF(7/10), ePub (5/10)
    • Documentation: (9/10) - this is the one that matters
    • Usability: (7/10)
    • Examples: (8/10)
    • Explanation of the general architecture: (5/10)

Updated: removed rant about documentation for another post.

Reviewing OpenLayers 2.10 Beginners Guide

Here is a recent tweet from Volker Mische of GeoCouch fame: Why people use web mapping libraries other than #openlayers http://t.co/e4V3VDS #wceu

Problems with Open Layers:

  • Documentation
  • Default Look
  • Usability
  • Examples are not good
  • No explanation of the general architecture
It is indicative that most of the problems above are not technical in nature, but reflect a lack of documentation. Update: Volker has an entire post which covers this list as does crschmidt.

I will use Volker's list to frame this review, how well does this book fill in the gaps mentioned above?

Typesetting

So what is Open Layer 2.10 Beginners Guide like as a book? It is one of the first ebooks i have tried to deal with directly, so the first step is sorting out how to read it in a productive fashion.

End Result, ePub may be the future of publishing, but at least on a Mac the future is out of reach - stick with PDF. To make this setup productive I needed to go grab a second monitor; one for the book and one to work in.

Edit: removed rant about documentation for another post.

Finally I printed out the first section to see how the typesetting comes across in book form.

  • Paper (8/10):

    The typesetting offers attractive with a clean and consistent presentation. The Typesetting features a distinctive look with bold wide headings that act like a black hole on the page (especially when reversed). In physical form this has been offset with nice wide white margins for an attractive balanced presentation.

    Code is presented clearly with line numbers so you can refer to a specific line. There is a missed opportunity here as the code does not have any kind of formatting (for example bolding keywords to enhance readability). While this sounds like a small issue it really starts to add up after a while especially when examples mix strings and javascript code.

    Sections are clearly marked, and importantly consistent allowing you to flip through the content and scan for sections such as "Time for action" that identify step by step instructions.

  • PDF (7/10):

    I have to guess that the eBook is intended as a supplement to a printed copy. There are a couple of things that let this use down: 1) the large margins detract from the on screen reading experience 2) Unfortunately the line numbers on the code examples are picked up when trying cut and paste into a text editor.

  • ePub (5/10):

    I am going to guess that the problems with ePub (on every single reader, and noticed by James Fee) is a quality control issue that the publisher can fix in due time.

Documentation

So does this book address Documentation as a weakness of OpenLayers?

I have two things I expect of a book aimed at beginners:

  • Instant, visual, satisfaction

    Basically make me a believer, or at least believe enough to continue reading.

  • "basic as a cookbook" instruction.

    step by step showing me what to expect as I go.

Open Layers Documentation

For comparison the Open Layers Documentation is mostly devoted to live examples. The major and probably underrated advantage is that these are a) always current b) easy for developers to maintain. There is also a FAQ which looks to be answering questions about the project (who cares?) and the start of Sphinx driven prose documentation which looks promising.

While the examples may be a good reference they really are not suitable for beginner docs. Lets see how the sphinx docs does:

  • Instant, visual, satisfaction? The sphinx docs start out with an Introduction that is perfect in this sense. The very first heading is Creating your First Map

    Total time for visual: 2 mins

    While this may not the best metric for evaluating a book it is at least how I evaluate when in a book store. Can I understand the "hello world", if not I hunt for a simpler alternative.

    Did I understand anything of what went on? Not at all (sigh). Simply adding the empty *script* block so I knew where to cut and paste into would help. Only reasons I was successful at all is because they put the example together at the end.

  • Basic as a cookbook? The sphinx docs fall appart here as they assume I know what I am doing (surprise I don't - where does the script block go again?). The steps were not numbered (helpful when all the concepts are new and you cannot tell the paragraphs apart). And surprisingly for open layers there is no visual included on the page showing what the results should look like (really important for a beginners guide as it is so hard to know if you have completed something correctly).

    To be fair these are probably not beginners docs and the intended target audience probably knows more than me about how things work.

So how does OpenLayers 2.10 Beginners Guide fair:

  • Instant, visual, satisfaction? (7/10)

    Getting something on screen is covered in the first chapter. While we do have to sit through an introduction and background information, we do finally arrive at "Time for Action" section on downloading open layers followed by "creating my first map".

    Total time for visual: 30 mins!

    As for the long time; I was unable to cut and paste from any of the reader formats (downside to those helpful line numbers).

    The following shows how selection works in the PDF:
    And the resulting paste into a text editor:
    map var
    );
    = new OpenLayers.Map('map_element', {}); wms = new OpenLayers.Layer.WMS(
    

    After typing things in managed to produce an empty map! After checking and rechecking for typos; trying in different browsers, I finally clicked on the page which resulted in the map being shown (a ha something is working!).

    A few questions on IRC (thanks crschmidt on IRC) and I was able to sort out my mistake:

            map.addLayer(wms);
            if(!map.getCenter()){
                map.zoomToMaxExtend();
            }
        
    Can you spot it? It should be map.zoomToMapExtent().

    So while I would love to give this one high marks for the clear instruction; it was a frustrating introduction to the book.

  • Basic as a cookbook?This is where the book really hits it out of the park.

    As other reviewers have mentioned, the second chapter on firebug really underlines the fact that this is a book aimed at beginners.

    While intellectually I know that firebug is the standard environment for working with Javascript without going crazy; I only know this from watching coworkers. So I am thankful for the kind introduction using a domain I have some familiarity with.

    In terms of the step by step directions I find Mr Hazzard's writing clear, and more importantly on topic. Any explanation is safely separated into a "what just happened" section so it does not get confused with the step by step instructions.

    The other important aspect of step by step instructions is the pictures allowing you to verify progress and have the all important reassurance that you are on track. The pictures are plentiful but not pretty. While I understand that the result needs to be printed in black and white

    I did suffer a little bit of platform and version burn during the initial install instructions; I wished that the instructions were given once each for (linux, windows and mac) as it is hard to follow a mix of linux and windows directories and then be presented a screen snap of some kind of linux file explorer in order to verify you did the steps correctly.

    Once the book gets underway these platform specific issues vanish. There is a small "bait and switch" with the preface indicating that you can use any browser followed by the second chapter being dedicated to firebug.

Still this an excellent example of how to write documentation for beginners, working with Firebug is really assumed knowledge that anyone calling themselves a Javascript programmer (and thus a candiate for working with OpenLayers) is normally expected to bring to the party.

The rest of the book continues in this fashion offering a nice logical introduction to key concepts.

One shock for me coming from a GeoServer background was how much isolation OpenLayers offers from OGC standards. A good example is Style handling with Symbolizers being introduced directly and no reference made to Style Layer Descriptor standard.

Default Look (9/10)

Next up on Volker's list is the default look of OpenLayers. In this case the book goes way beyond what I was expecting from a simple beginners guide. There is an entire chapter devoted to themes covering how to style the controls use by OpenLayers.

I am not sure what the OpenLayers examples are like in this area; but I expect the book will help websites migrate away from the default looks.

Usability (7/10)

Usability is going to be one of the technical issues on Volker's list. This usually comes down to making a web application both simple and direct to work with, and "snappy".

The book does manage to mention performance in a couple of sections; and emphasises the benefit of a fast web mapping application along with specific guidance on TileSets vs WMS. It also goes through the exercise of cutting your open layers file down to just the parts needed for your web mapping application.

So for a beginners guide this book is aware of performance and usability issues and takes some steps to address these matters.

Examples (8/10)

This is an interesting entry on Volker's list - "The examples are not good". Personally I like the examples on the OpenLayers website, but I agree they should not have to bear the entire responsibility for documentation.

The examples in the book are more in the nature of step by step instructions, while I have a terrible time cutting and pasting out of the PDF, they are effective and plentiful.

One thing I would love to see in both the book and the website is the use of the natural earth dataset (or any other attractive dataset). The default blue and white map has come to define what OpenLayers looks like; and while it may be functional for examples I am sure we could come up with something more exciting.

Explanation of the general architecture (5/10)

This is an interesting topic to consider with respect to a Beginners Book. I certainty feel like I know some of the moving parts in an OpenLayers application, but I expect I need to build a few applications to feel comfortable.

With that in mind this book really does span a broad range. Starting off with some object oriented basics in Chapter 1 (for those new to Javascript). A couple of reference sections for the key concepts of Map, Layer, Vector Layers and Style. With a chapter on Making a Web Mapping Application bringing it all together.

So as a reference the book performs admirably. Does it address Volker's question about the general architecture? Probably not. I would of loved a picture of how open layers fits together to give me a better feel for the general architecture. Indeed I almost expected one after being introduced to Object Oriented concepts in Chapter 1.

Recommendation

I am happy to recommend OpenLayers Beginner's Guide, it offers a nice introduction set at the correct pace for beginners in web mapping. The publisher has an opportunity to fix may of the technical difficulties present with the electronic editions of this book.

Desktop eBook Reader

I have finished up my review of the OpenLayers Beginner's Guide. The first hurdle was searching for a good eReader that would both let me read the book comfortably; and have it open next to a text editor while working through the examples. Little did I know this would prove a challenge!

So what are my options for reading on a Mac:

  • PDF: Traditional solution, only hesitation I have is based prior experience copying code examples out of a PDF document (tends to bring in garbage such as headers and footers.

    Still the default mac Preview application is very fast at displaying PDF content and the result looks great on screen.

  • PDF on Papers2: Ended up using Papers2 which is a bit of an overkill as it is really set up for sifting through hundreds of documents allowing you to cite passages and so on. This was a good way of checking that the PDF metadata was in order (or match it to a search result).

    It does have a nice full screen reader which is great if you enjoy a cupa while sifting through a title such as this one.

  • ePub on Calibre: Ended up downloading Calibre to check how ePub looks in practice.

    The result is easy to cut and paste from, but leaves a lot to be desired in terms of readability. I also found the occasional "glitch" using this application ( lists appearing as "1. 1. ","2. 2." or tables being rendered with text floating on top of other text).

  • ePub converted to MOBI: This is another popular recommendation for mac users. Use Calibre to do the conversion, and then read the book on a Kindle (or with the Kindle application from the app store - although I could not sort out how to get that to work).

    I gave this one a go, and the result is nice and readable book on the kindle, while some of the formatting did not make it this is a good option for taking the book to a local coffee store.

  • Digital Editions: Against my better judgement I downloaded Adobe Digitial Editions to try a more professional ePub reader. The flash based installer really set my teeth on edge; the resulting application looked like a web page gone rouge and pretending to be an application. No application menu, custom scrollbar widget so I could not see how far along in the document I was and so forth.

    Digital Editions was not able to open up the zip file provided. Opening up the *zip* file in the finder produced the epub document for a brief second before it was unpacked in turn into a folder containing a MANIFEST and html pages (Which Digital Editions could not read either). While I could use an application like Pacifist here, able to point it at the epub document that Calbre unpacked allowing me to get something on screen.

    The result did display quickly with fewer glitches then the eReader built into Calibre.

  • ePub on Reader Libary Software: Sony provides a recommended reader which I am sure they intend for use with their own ebook readers. An initial improvement on Digital Editions was an actual installer, however it forced my computer to restart (really? are you sure you are just an ebook reader?).

    The application is similar to a housebroken version of Digitial Editions; while suffering from the same inability to unpack a zip file the result does behave like a mac application (help available in the application, it has a title bar and so on). The one really odd thing was the MASSIVE choice of font size; the above screen snap is actually set for XS (extra small).

  • ePub on Stanza: Nice Drag and Drop installer this time. However the result was scary with no trace of formatting. While I am sure this is a design decision well suited to novels it renders a technical book of this nature useless.

End Result, ePub may be the future of publishing, but at least on a Mac the future is out of reach - stick with PDF. To make this setup productive I needed to go grab a second monitor; one for the book and one to work in.

Tuesday 10 May 2011

WKT and ArcGrid

A couple of documentation updates from email this time.

CoordianteReferenceSystem and Formattable
The first is an example of how to take control over the generation of Well Known Text when describing a CoordinateRefererenceSystem; credit to aaime for the email/text:
CoordinateReferenceSystem crs = CRS.decode("EPSG:32735");
Formattable f = (Formattable) CRS.decode("EPSG:32735", true);
String wkt = f.toWKT(Citations.ESRI, 2);

ArcGrid
The second example comes from the user list and concerns the use of ArcGrid data (an ASCII format). The user guide did not have any specific code examples as this format is supported out of the box by GridFormatFinder:
File f = new File("ArcGrid.asc");
// Reading the coverage through a file
AbstractGridFormat format = GridFormatFinder.findFormat( f );
AbstractGridCoverage2DReader reader = format.getReader(f);

GridCoverage2D gc = reader.read(null);
I did dive into the test cases and actually found a wealth of additional capabilities reading from an ImageInputStream, InputStream, smooth handling of gzip, or just reading from a URL.

Documentation harmed in the making of this post:

FOSS4G Presentations Feedback

Planning what presentations to go to at FOSS4G is always difficult; how much more difficult to go through the extended dance remix of all the submitted presentations?

In the past the selection committee has often provided guidance to the selection process based on the conference themes. This year they committee did provide guidance to those submitting:
  • Case Studies (these are always popular; I find that reviewing the slides is good; but being there in peson for the Q&A session is usually the best part).
  • Benchmarks (You hardly need to attend these; just have twitter open; once again the Q&A session is usually the best part. I sure wish they would include "setup time" as a benchmark.)
  • Visualization (integration by eyeball - always a good choice)
  • Development (hard pressed to attend these myself; BOF is where the development action happens)
  • Hacks and Mashing (they should of just called this one "Fun")
  • Open Data and Collaboration (this is a tough one; you can either end up with something fun, or get stuck listening to policy discussions)
In general I find advice of this nature to be helpful - it gets me thinking about what makes an successful conference.

Surprisingly all of guidance vanished when the public was asked to rate presentations.

The rating system consisted of (with a few additions by me):
  • +2.0-means you are very interested in attending the presentation.
  • +1.0-means you are somewhat interested in attending the presentation.
  • +0.5-means you opened up the topic to see "more" detail
  • +0.0-means you are not interested in the presentation.
  • -0.5-means the opening sentence made you hunt around for a "less detail" button.
This is an amazing take on things; in particular the "filter" field; I would *love* to see a summary of what people filtered by! It did not always work for me; searching for "Jody" listed WPS Shootout, but not State of GeoTools.

A couple thoughts as I sift through the possibilities:
  • I found so many interesting presentations; stuck behind awkward titles. Even if I would like to go to these presentations; they would not make the conference a success (as people browsing the program during the conference will naturally skip over these).
  • What I am interested in attending so *so* not what is needed for a successful conference. Watching five presentations on WPS; where each spends 5 mins explaining the background of what WPS is hardly counts. I sure wish there was a little organisation to the rooms; so an intro to the topic could be covered by the details/success/case studies by each team.
  • There is a lot of pressure on this selection process; various project mailing lists have been asked to "vote for my proposal". This is really tough as often justifying attending the conference comes down to getting your proposal accepted.
  • I love finding new projects in this list that I have not heard of!
  • Interesting 52N submitting a presentation agains the "Open Geo-Stack". The company OpenGeo has an OpenGeo Suite; so either the hypen is in the wrong spot or we are going to have a bit of marketing trouble ahead. One down side to various stacks being constructed and branded is going to be confusion like this. As a customer having a stack that is tested will be great; however it does place an increased communication burden on all those involved.
  • Please don't being your description with "yet another XXX"
  • Many of the talks I would like to see are boring; ie they are focused on the details and open my mind to possibilities. It is much more exciting to see SDI wrapped up and polished for use; but I got tired of that a while ago. That goes double for securing OGC services.
  • Andrea is doing a great job of collaborating with members of the community that cannot make it to FOSS4G. Thanks Andrea!
  • Note when submitting a bunch of talks (in the hopes of getting one through) you have a chance of splitting your vote ... and not getting any in.
  • I always confuse MapBuilder and MapBender
  • It is a hard balance between presenting your company; and presenting your project. Always figured that is what renting a booth was about? (Or taking a BOF session out to dinner?)
  • GeoREST? Interesting examples from Nanaimo and Vancouver (I suspect Nanaimo is a right of passage for any geospatial technology these days; kind of like the teapot for 3D graphics)
  • Comparisons and gap analysis is always popular; I wish as much effort was spend filling in gaps.
  • really nice to see a presentation on adoption that talks about risk right up front.
  • A case study with "Getting the bugs out" in the title does not sound optimistic!
  • A fair number of case studies on making the migration from ESRI only solutions; I always advocate moderation (in terms of risk; not price) - but it is nice to see these presented as success stories
  • It is really nice to see small business (and small municipalities?) targeted with presentations - this is a market I am never really in position to help. Perhaps the "stacks" mentioned above will allow them to invest in open source?
  • Had never heard of "JackPine Geospatial Database Benchmark" before; wonder if they are allowed to publish Oracle results (or is it a case of run on your own hardware)
  • Please be careful if you are presenting any comparisons (especially on "compliance"). Communicate with the various communities (on their mailing list) before the conference. Even if it means adding a slide with "breaking news" at the last moment.
  • A really large number of INSPIRE based presentations for a confernece in the states?
  • A number of presentations on hydrology? Wish for a panel discussion instead.
  • GeoScript for WPS? That would be cool - really wish ZooWPS would adopt GeoScript (or at least compare notes, or head to head comparison)
  • There is a real difference between "dry" abstracts and those that sound fun or entertaining
  • A lack of standards "basics" being covered; will need to remember to do a talk like that next year
  • No tribes talk? That is the other nice general intro
  • So MongoDB gets a DataStore for GeoServer? But GPL keeps it from being donated back to GeoTools (for use in GeoMajas, uDig, 52N etc...). Still very cool to see the NoSQL database options being integrated
  • EduGIS gets it; a successful education outreach includes both software and leason plans
  • TinyWFS - finally some choice for WFS-T
  • So many security presentations; sure wish for a panel discussion
  • The difference between describing a talk as cartography vs Map design, usability and interaction is the difference between night and day.
  • Handy tip; only Java shops know the keywords "enterprise level" - everyone else just wants results. Still would be nice to see a Geomajas talk
  • Almost any talk on JTS is going to be amazing although it is really hard to communicate that. There are always a couple of talks where "the development teams" go to listen at each FOSS4G. There is that classic moment where the rest of the conference asks "where did they go?".
  • It would be great to talk to the OGC Schema guys; pushing JAXB way beyond its comfort zone
  • In this context do we really need to say PostgreSQL/PostGIS?
  • PostGIS 2.0 vs State of PostGIS?
  • Sigh! FOSS4G will be great this year!
If you do want to go to the extended dance remix of FOSS4G; join us on internet where the code lives :-)