GeoTools moves to OSGeo Repository

The GeoTools project has moved repositories today - to hardware maintained by the Open Source Geospatial Foundation. We would like to thank Refractions Research for giving us a home for the last five years (they kindly provided an svn repository for us when Source Forge was going through some growing pains in 2003).

The new hardware is faster and has a better connection which will result in a faster build time for those building with maven.

The new code repository is located here

• http://svn.osgeo.org/geotools

To migrate an existing checkout to this new location please use:

svn switch --relocate http://svn.geotools.org/ http://svn.osgeo.org/geotools .

or

svn switch --relocate http://gtsvn.refractions.net/ http://svn.osgeo.org/geotools .

This move also opens up a new maven repository (used to host the compiled geotools artifacts so other projects can use them). 

Documentation that has been updated in response to this move:

• Source Code (checkout instructions)
• Committers (how to get commit access)
• First Project

Translation using Resource Bundle Editor

One great way to get involved with an open source project is to help localize! On behalf of the User-friendly Desktop Internet GIS project I would like to welcome a couple of recent volunteers with some updated documentation on the Resource Bundle Editor. 

The "Eclipse Resource Bundle Editor" is a great little front end for editing a bunch of properties files - each one of which contains the human readable text that is slotted into the appropriate place of the application.

This plug-in has been folded into the Eclipse "Babel" project that appears to be building up a massive database of everything that would normally live in these property files; and then they generate the property files on demand.

Jesse Eichar has been kind enough to bundle up this plug-in with enough extra stuff that anyone can run it; instructions and the required links are on the Adding Translations  of the udig admin website. If you would like to help out you can follow the instructions on this page to translate uDig - without any development experience.

The other thing we capture as part of the uDig experience is online help in the form of a User Guide. This guide is captured as a wiki; and we have several wiki spaces - one for each language being made available.

For the translation effort starting up we have the following newly created spaces:

- Portuguese

- Brazilian Portuguese

For the translation of uDig into Portuguese it sounds like a nabble forum will be used for organization:

- http://n2.nabble.com/udig-translate-pt-f1631192.html

Documentation Harmed in the making of this post:

- http://udig.refractions.net/confluence/display/ADMIN/Adding+Translations

GeoServer Community Schema Installation

One of the surprises I found working at LISAsoft (and indeed in Australia) is a history of success with the GeoServer Community Schema branch. Previously my best advice to anyone interested in this area was to hunt down Gabriel or Rob and ask them for help.

Mark Leslie was able to point me in the direction of documentation on how to install and configure the GeoServer Community Schema branch. Apparently Rob has been publishing a war file; and this documentation covers how it can be used.

Since this documentation is available under a Creative Commons license I have posted it to the GeoServer wiki (see GeoServer Community Schema Installation).

The concept of a "Community Schema" is important for anyone working with a rich feature model where they are expected to produce out put that confirms with a pre-existing XML Schema. Occasionally governement or standard organizations publish an XML Schema describing a data product that should be made avaialble *exactly* as described.

Open Source Developers Conference - Sydney

Today is the last day of the OSDC Sydney and it has been an entertaining slice of life on the programming side of the street.

I was able to attend due to the worldly Mark Leslie (PostGIS committer who has been missing a lot) being stuck in Thailand. Indeed he was so stuck he was unable to give his talk.

Here are some notes from an intrepid attendee:

- http://myownhat.blogspot.com/2008/12/openspatial.html

As they say here "It is all good". I will provide a link to the slides when I find a server to hold them.

It was interesting that "Location Based Services" made the list of annoying marketing buzzwords this year - along with "Cloud" "Ajax" and friends.

Incidentally Mark has now made it back safely.

Update:

- Python 3 is proving an amusing hurdle for people

- PHP "Traits" seem to have a bunch of the goodness I previously thought was the benifit of Fortress :-) You can get the patch from the wiki (is small clean and can be applied). Decision to take it in has been made - but is waiting on the swith to svn or something.

- Open Australia - seems to be the same track the political thing that we had going in Canada (at least before the Canadian developers made the transition to Ruby)

- An interesting web testing thing that will abuse a range of browsers called Watir

- The lightning talks are very good for watching linux machines reboot as they come to terms with a projector (on the bright side it makes the talks faster and slide free).

- Apparently POVRay (which Paul Ramsey mentioned) has recently gone through the same sort out who wrote the code process that GeoTools suffered - and now can consider moving to GPL 3.

- Microsoft is here and gettling along well (IronPython for example) - they keynote was given by a member of the SAMBA team and also points to mending bridges

- Our mates that provide Confluence, Jira and so on to Codehaus are here with a OSGi based plugin system (that is Spring, Pico etc agnostic). Sure wish they had released that last year; the result looks similar to the Eclipse plugin.xml experience but for server side OSGi apps.

- A good talk on using visualization for rolling out the difference between testing and/or production webservice testing

- Sun was here pushing MySQL (complete with compition for a plasma tv requiring only in depth MySQL knowledge)

- Larry Wall gave a lovely talk with many nice pictures; and the occasional code examples. The contrast with the Python 3 roll out in terms of time taken is interesting and it will be interesting to see how communities handle the migration. Still anything that can help regex get sane will be a useful tool.

- There are more thinkpads here that macbooks here

- Nice lightning talk thanking Larry for Perl (I thank him for his witty writing more then Perl)

- bazzar (or is that bzr) is already taking hold; get and mecrurial also mentioned

My laptop cut out and the remained of my notes were lost! I remember Perl 6 being out before Python 3 and a revolt in the PHP community over the use of \ as a name seperator.

Most of all I was amazed to see the programming languages being run like normal open source projects; I kind of thought they would be more you know stuffy and academic or something.

Microsoft was kind enough to donate test hardware (with all the different versions of windows available in virulized form) to the CSPAN Perl community.

Apparently this offer is open to other organizations - perhaps something OSGeo would be interested in. I would welcome the chance to test on Windows Server 2003 (since I always get odd bug reports from that environment).

MapGuide shaping up

I have had a couple of positive experiences with MapGuide  over the last year. I took part in a training course in in February at Sejong University and MapGuide was well represented in recent series of GITA workshops.

The good news - it is time (for me at least) to take MapGuide seriously.

Is it the source code? Not really - I expect that of an open source project. I find the PHP code examples easy to follow; and the applications I have seen built up around this base seem to be clear and straight forward. A few things came across as difficult: I listened to tails of how hard it was to change selection color from blue to anything else (apparently it was hard coded).  More troubling was a constant theme of difficulty building (both in February and on the recent GITA workshops). Making a project easy to build is always a priority for me - if a developers is willing to build the code they are *exactly* who I need to produce and submit patches to my project. So the source code could use some work.

Is it the license? Well I always admire an LGPL project - generally less hassle for me as a consultant to find work with. But I am willing to work with anything so it is not the license.

Is it the product? The demo provided during the GITA workshop was well suited to the audience and really illustrated a point I often try to make - namely that open source projects need to be fast to try out and see results. If you are spending tens of thousands of dollars on a product chances are you going to try and use it for a couple of days; and perhaps read the documentation. An open source project operates under no such illusions - installation needs to be quick; and the applications as straightforward as possible. So I am afraid the product is what I have expected (it actually reminds me a lot of the Deegree experience).

What changed this time around for me was this ... the people.

Or more to the point one person; Zac Spitzer was an real live developer overjoyed to get things done; and enthusiastic as all get out. He had the usual tails of grabbing patches from trunk and applying them to a system just in time to make delivery; all the kinds of things that we forget are amazing in the open source community.

An advocate such as Zac was exactly what was missing from my previous experiences with Map Guide.

Zac it was nice to meet you; I look forward to seeing what trouble we can cause in the future.

OSGeo Branding

A recent post on clever elephant has touched on a topic near and dear to my heart - the value (or lack there of) of OSGeo as a brand. This discussion; and the importance of it, was one of my initial passions with the idea of OSGeo (and one aspect that interested the GeoTools community in the process).

I find that the current web site is very much focused around the foundation itself and the member projects. I would like to see a different approach namly to focus on the products and the abilities of the open source geospatial software.

I started just such a discussion with the web committee in 2007 - before the prospect of getting GeoTools through graduation sucked up all my time and energy. My understanding is the marketing committee currently has the mandate in this area.

Here is the WebCom OSGeo Site Focus wiki page where I gathered up my ideas last time.  The idea was to profile example users - where each user has an answer they are looking for:

• Government: Dave is checking out OSGeo after hearing good things during a recent visit by members of GeoConnections Canada. He is impressed with the public / private partnership represented by this government policy and wants some more information on how it is done.
  
• Government: Mary is a volunteer from a small non governmental organization wanting to do local planning
• Government: Josh works for a municipal government, and is highly constrained by both staff time and budget. He has looked at open source geospatial before, but was unable to dedicate the time to figure out how the pieces fit together.
• Education: Sebastien is a graduate student starting research into his thesis and wants a platform to base his work on.
• Education: Sarah is an undergraduate looking to have her homework done
• Users: Peter is into Geocaching. He wants to have tools to help with his hobby. Ultimately he wants to share these tools with his friends.
• Users: George is an ESRI Professional who has been told by his manager to look into what is going on.
• Users: Lui is GIS Professional looking for cheap way to try out an open standard.
• Developers: Chris is established developer will be annoyed at any change that slows him down.
• Developers: Adrian is starting out wants to know what is here and how/if it works. Really wants to get working but cannot make sense of the documentation spread across 5 standards, three projects and apparently communicated via Zen

That is probably enough direction for a reorganization ..the really hard part here is to motivate the production of content for the website - in the past I had two hopes for content production:

• Consulting Organizations (similar to Refractions, Camp2Camp etc...) that wish to demonstrate expertise in a particular area. We can ask such organizations to submit white papers; case studies, tutorials and so on. However to preserve the OSGeo Brand we really need to make sure the word
  

• Incubation Committee really needs to communicate what information is expected from projects as they join up. For projects that are already out the gate we will need to catch up with their PSC representative and beg for source material.

I am less hopeful now - seeing the recent GeoServer branding exercise I am going to have to add:

• Graphic Designer - we probable need to hire someone. Or if the marketing committee can scare up a passionate volunteer

In doing the research for the wiki proposal mentioned above I went through several websites; apache.org , eclipse.org and the OGC site. There was a contrast in approaches; apache reduced their branding to single logo stamped on each web site; eclipse.org and the OGC site were much more user aware providing common navigation; background papers and such like to help people make informed decisions and not lose their way.

The idea of OSGeo as a brand has also come up with respect to sponsorship and project participation. I have gone over the same three websites with a prospective sponsor - with the idea of seeing what they would get for their money with each a approach.

Several interesting observations were made - on our website currently sponsors are safely sheltered on small web page. This approach can be contrasted with the OGC site where a rolling banner shows sponsor logos. 

A second difficulty was that it was hard for a sponsor to communicate their expertise in a given area or with a given product. The pages for each product had no room for sponsor logos for example. In this the eclipse.org site shares our bias - on eclipse.org the only way to figure things out are to look at who members of the steering committee work for. 

Welcome to Lisasoft - and Nearest Book

I just picked up on this Nearest Book meme over on Sean Gillies blog; this was really good timing as my freight from Canada arrived today at LISAsoft  HQ. I actually arrived at LISAsoft last week but have been on the road at a series of GITA workshops as seen on Zac's recent post.

So with out further ado:

A five point priority scale also works well.

Luke Hohmann, Beyond Software Architecture  . The phrase is part of a sidebar on "Bug Severities, Priorities, and Normalization".

I keep this book close to act as my conscience as a software professional; it contains all the advice and perspective I lose when I get excited and close to the raw code. Which is not to say it is perfect; this phrase is part of a chapter called the Difference between Marketecture and Tarchitecture :-)

If you would like to play along:

1. grab the nearest book
2. open to page 56
3. Find the fifth sentence
4. Post the text of the sentence in your yournel along with these instructions
5. Do not dig for your favorite book, the cool book, or the intellectual one: pick the CLOSEST.

Whew - it is a good thing this was about books; the closest thing I have unpacked is the Family Guy in geek friendly UMD format.

GITA GIS Technology Workshops

I am going to be attending the GITA GIS Technology Workshops:

• Brisbane: 5th November,
  
• Sydney, 11th November
• Melbourne, 13th November
  

Hopefully I can hunt down the members of the OSGeo Australian-NZ group (which I had the honour of putting together a logo for).

James Phone Home - GeoTools.org needs you

The GeoTool DNS Entry has lapsed; so the web site is available here:
- http://docs.codehaus.org/display/GEOTOOLS/Home

To continue to work with the source code:
- http://gtsvn.refractions.net/

Todays IRC logs are here:
- IRC Logs Oct 27th

We will be hunting down our honoured founder (ie James) who is charge of the domain.

Moving on

One of my great joys in this industry is performing introductions. As an open source advocate I get to make a lot of introductions to all the helpful people that make up our community. As a proponent of standards I get to help people wade through the OGC site. When doing a workshop I get to introduce specific technologies, and occasional geospatial concepts.

It is all a great deal of fun.

Recently I was asked "how I learned all this stuff".

The answer is a story. In 2003 I moved to Victoria (British Columbia) to start a new job. Dave Blasby (a friend of mine with mad skillz) recommended this small company operating out of what appeared to be a roof top green house overlooking a square. I had actually worked with a couple of the characters before. Paul Ramsey (as a mad Perl Hacker, operating like an Alice in wonderland creature with hap-hazard limbs clustered around a keyboard speaking in regexs) and a quiet new guy called Graham.

The second step was due to a hobby of mine - swordsmanship. Shortly after starting this job I managed to break my thumb (over a small argument of philosophy with pole-axes).

My recovery time was spent trying to build GeoTools with one hand; and reading all the OGC specifications – even the boring ones. Not a kind introduction but it seemed to do the trick.

Today is my last day at Refractions; I am really excited about the next adventure I have lined up but I want to take a moment to thank everyone who has made the last five years such an incredibility rewarding experience.

Thank you.

uDig 1.1.0

If you check the uDig download page you will see uDig 1.1.0 is available.  Please see the official announcement for an overview of what is new, and the organizations that made it happen, etc...

Apparently this is good timing for a release; a recent uDig GIS: A First Look article was published in the Linux Journal.  If you are new to uDig (in addition to the article above) please consider the following resources:

• Quickstart
• Walkthrough 1
• Walkthrough 2
• Running uDig

This has been a really interesting ride leading up to uDig 1.1.0. The project has migrated from a core developer team located in Victoria to a diverse set of developers from all the corners of the earth.

Much of this transition has been under the leadership and support of Jesse Eichar. I would like to personally thank Jesse for supporting development teams - often on his own time as a volunteer. I am especially pleased that his hard work supporting others has been echoed back on the email list in terms of testing, translations and feedback.

A friendly reminder for the GeoServer project; it appears they have a ways to go before they catch up to our Release Candidate record.

FOSS4G Round up? Welcome back to the Internet

News from FOSS4G has been very light this year; one of the only round-ups I have found is from Directions Magazine.
 
The article highlights Digifesto blog post - "FOSS4G2008 - Culture shock" which is shocking to me for a number of reasons. The main one stems from a representation of the OSGeo mission statement that I find troublesome.

Here is the actual mission statement:

The Open Source Geospatial Foundation, or OSGeo, is a not-for-profit organization whose mission is to support and promote the collaborative development of open geospatial technologies and data.

I would like to thank Sebastian for providing some of the only coverage to date on FOSS4G - the real standout blog post is this one - "Get Real". I spent some time in Africa and this post covers some the central problem of applying solutions, that are often Internet based, into an in appropriate context.

I join everyone in offering Paul Ramsey congradulations on getting this years Sol Katz Award.

Jesse Eichar was kind enough to send a Summary of Foss4G to the udig-devel mailing list. Word on the IRC channels is that FOSS4G was a success, everyone is still tired, and that blog posts will need to wait until a decent internet connection is found.

Welcome back to the internet OSGeo members - I missed you!

Applying the Secrets of JTS

FOSS4G is next week - let me share a little gem from last years FOSS4G conference - Martin's Secrets of JTS presentation.

Talks like this cover material you can revisit, and revisit and revisit. Although Martin does his best to make JTS numercially stable; his presentations can sometimes induce a little recursion.

I revisited this set of slides today as I went over how to "snap" points onto a line - as fast you possibly can. The general set up is some laxidasical source of data that you wish to "auto correct" with the wild assumption that cars stay on roads (or the even better assumption that you have data for all the roads).

The general approach here is to take a peek at behind the API; in this case we can explore the technology that makes a method call like geometry.getDistance( point ) possible.

Here is the heart of the code example - for details see the GeoTools user guide:

Envelope search = new Envelope(pt);
search.expandBy(distance);
        
List hits = index.query( search );
double d = Double.MAX_VALUE;
Coordinate best = null;
for( LocationIndexedLine line : hits ){
  LinearLocation here = line.project( pt );              
  Coordinate point = line.extractPoint( here );
  double currentD = point.distance( pt );
  if( currentD <k d ){
     best =  point;
  }
}
if( best == null ){
    // we did not manage to snap to a line?
    // with real data sets this happens all the time...
    System.out.println( pt + "-X");
}
else {
    System.out.println( pt + "->" + best );
}

Documentation harmed in the making of this example: Using SpatialIndex and LocationIndexLine to Snap points.

Workbench selection - Who watches the watchmen?

Well you may alread know the answer.

As mentioned a few posts ago; one of the tricky areas to get going on with Eclipse RCP development is understanding how "workbench selection" functions.

Developers usually know what to expect from using the Eclipse IDE - you work away; and the rest of the IDE leaps into action providing more information about the selected method / selected class or selected something.

But how do they do that? And how can we make use of the same facility in uDig development?

I do not want to spoil the fun; please check out a new workbench tutorial on the uDig website, and thanks to Chris Luft for putting this one together. The view you create in this tutorial is really helpful for understanding how things work; and can be used to debug your own applications.

This tutorial really brings home why Eclipse RCP is such an excellent platform for your next project.

Documentation Harmed in the making of this post:
- Workbench Tutorial (Developers Guide)

Using Maven to Work with Others

I have watched a number of developers fall over the handling of Maven SNAPSHOTS today; so it was time to take action.

The general idea is an email is sent out saying "new snapshot deployed please build with -U" - here is what that means:

1. Update

   svn up

2. build using the -U option

   mvn clean install -U -Dmaven.test.skip=true

The above example skipped the tests (which is common when you are trying to pull down a quick update and keep working), please note by definition that "-U" is not compatible with the "-o" offline mode.

If you are working on uDig there is an extra step; you need to run the libs refres.xml script which will use a "maven ant task" to pull the changed jars in for your.

Documentation harmed in the making of this post:

• Working With Others (GeoTools Developers Guide)
  

Community and Communications

I had an amusing pairing of emails today:

• a nice email from an OSGeo education committee member asking me to take part in some research on how open source projects collaborate
• a full email box we iron out the relationship between GeoTools and the ImageIO-Ext project

For background GeoTools is "run" by a project management committee. In recent years the Open Planning Project has acting as defacto maintainer as they make releases for the excellent GeoServer product. Refractions (and other organizations) have been taking part on the research end of things. Actually the Open Planning Project has been doing a bunch of research as well - I just want to thank them for keeping the release train going...

These two forces are in opposition; new functionality is the enemy of stability. Processes were introduced to help with stability; process cuts down research (due to adding overhead). So a compromise of the "unsupported" module was born - an area of svn where experimental (or unloved) work could exist without being deleted.

This has been a great compromise - it allows us to welcome in new developers and see what they are up to (without getting them to pass all the QA checks and code reviews). We figure once we have them involved we can buckle down on them later - when their code runs - and ask them to upgrade their module to "supported' status and thus have it included in the library for download. One of the nice things an "unsupported" module enables is the experimentation with "Fun New Stuff".

The ImageIO-Ext project reads like a text book example of "Fun new Stuff" - it combines GDAL goodness with Java Advanced Imaging goodness. And at least while it is under development it will be stepping on a few toes and taking a few short cuts while the idea is proven as real and good.

Since my mail box was full today - I expect the ImageIO-ext project is getting close.

Here is what I am going to try for going forward:

1. The 2.5.x release story with unsupported/supported modules needs to be clear.
a) I figure deploying unsupported modules to maven is okay for right now; it is a good move that allows new contributors to join geotools and contribute (which is the goal here)
b) The user list wanted unsupported modules as a separate download as well (I asked them after the last meeting). I don't want to do this:
- making unsupported modules available for download would take away a motivation for making a module supported.
- The GeoTools PMC should not be asked to take responsibility for code we have not reviewed (indeed by definition it does not meet the project standards).
c) We always get stuck on the unsupported modules that lack a module maintainer - these modules are *required* for one of two reasons:
- For modules that are required to complete a product story (Oracle Datastore I am looking at you). Frankly we are in a bind in these kind of things; as long as GeoServer keeps shipping with Oracle support Refractions can not make a good play to get a support contact (and make Oracle supported). We have customers interested in paying; but no threat is evident. Should we ask GeoServer to stop shipping Alphas with Oracle support?
- For new unsupported work that is required for the library to build or function (xml parser stuff I am looking at you) we need to see if these can be brought in as supported modules. If we must we should make a new category for this kind of work - I need to emphasis that this is important - the modules we are talking about here are set up to address long term goals of the library (goals that may not be reached with in a single contract, or within a single geotools release). I would even consider "accepting" these modules as supported - with a known deficit of say test coverage.

2. Review of dependencies
a) We have had several good discussions about dependencies - usually this focus on minimizing duplication (do we need 3 time support libraries?). Minimizing dependencies is a great direction to take and one it looks like everyone is motivated to follow
b) Todays discussion about what we expect from a dependency is a good one
- We expect open source? no. Or at least a dummy jar so we can build? usually. Or a profile so code written against a proprietary jar does not upset other developers? yes.
- in terms of distributing a dependency I want to focus on that only for supported modules
b) I expect unsupported modules to work with extra dependencies beyond what the rest of the library is using:
- Remember the goal here is to capture experiments that otherwise are lost to the public community - experimenting with a new dependency is a great use of the unsupported idea
- I need to respect the fact that unsupported modules are often work that needed to get done right now - as such I don't hold them to a high standard of review
- I would like to welcome outside contributors to contribute plugins and Adapters allowing GeoTools to work with additional libraries (Jump? Deegree? Sextante? gvsig?). Providing an area to work (and the ability to be versioned along with the GeoTools library) is a good enabler in this respect.
c) We need to be confident of dependencies we package up for download and distribution
- going through the website is a good start
- spots checks are a fine idea
- we should focus on the supported modules that are part of the library
d) Projects such as uDig and GeoServer that make use of unsupported modules (via maven dependencies) do so at their own risk - GeoTools makes no assurances
- hopefull by the time a module is ready for supported status the dependencies have been vetted; we should put this as a requirement for a supported module

In the specific case of imageio-ext I want to make sure the unsupported jars are not package up for download by innocent bystanders . For non-innocent bystanders like uDig we will help where needed before nominating the jar to be included in a GeoTools release (ie supported status). Currently imageio-ext is central to our story of supporting additional raster formats; with Eclipse RCP framework we have the chops to handle the platform dependence issue - I am not interested in being pure Java (I already have an SWT dependency).

GeoTools is moving out of the fast paced world of research and into the quiet solitude of maintenance. Careful attention to details as we make this transition is going to be very important - wish us luck! And we always accept volunteers.

IAdaptable

I am going over my notes from my last batch of training courses - and I find a couple Eclipse RCP topics need work.

Here are the topics:

• Plug-ins: the organization of code into plug-ins; that are wired up using the Platform object.
• IAdatable: a neat trick allowing code to be added to an Object at runtime
• Workbench Selection: the workbench tracks the current selection; allowing you to listen to what the user is up to in one handy spot

I was going to write up something fun and witty for IAdatable today - but I found an excellent article "What is IAdaptable" instead. Thanks to EclipseZone for keeping track of this stuff.

Documentation harmed in the making of this post:
* IAdaptable (uDig Developers Guide)

Why Java on windows ignores your PATH

This is kind of and old tip; that is very frustrating until someone tells you about it. And then it is still frustrating. Java on windows uses a placeholder in the System32 directory; this placeholder looks up the correct version of Java in the registry and calls that.

No "JAVA_HOME" environmental variable needed! Unless of course you are trying to use something like Maven or ANT which likes the idea of an environmental variable.



The trick is to change your PATH so that JAVA_HOME\bin is added before SYSTEM32.



Documentation Harmed in the making of this post:

• Java Install (GeoTools Developers Guide)
  
  

The only sane response to XML...

I have been helping several people get a handle on the various flavours of xml madness available to the modern map.



Documentation harmed in this endeavor:

• XML
• Overview of Parsing Technologies
  

There are a range of options from primitive SAX parsers through to "schema aware" parsers that seem to care more about being correct than the data itself :-)

The big weakness with all these technologies right now is error reporting - it is very tricky to tell what specifically went wrong, where, when and why.

The XML Developers Guide makes for some good background reading - in addition to being interesting (it is aimed at developers creating "bindings" for new schemas) it offers a few clues on what can go wrong.

Using Cartoons in Tutorials

I have just finished reading Joel's book on the best software writing. One of the best ones was an intro to Ruby using cartoon foxes.



Perhaps there is something to it?

Welcome to NetBeans users

Continuing this theme of pointing out hapless documentation contributors ... this week the user list covered how to get your hack on for the NetBeannies among us.

This time Michael Bedward has stepped up to the plate; in addition to answer questions he has written up some docs on on the wiki. For those wanting to use GeoTools the user guide has: Welcome to NetBeans developers

This is a great little tutorial; screen snaps showing each step along the way. Almost temps me to try NetBeans (if only for the maven integration; not having to install subversion - they make it look easy). Perhaps for my net GeoTools training course :-)

For those wanting to fix up the library (join us please) the developers guide has also been improved: Using NetBeans with GeoTools.

Thanks for the docs Michael.

What is the deal with GeoAPI

One of the great thing about working on an open source project is the wide range of expertise you suddenly have access to. For me the expertise often takes the form of well documented Java interfaces provided by the GeoAPI project; and it is the GeoAPI mailing list I turn to for help when "I just don't get it".

This weeks question comes from Tim Swanson of Tyler Technologies (welcome Tim and keep the questions coming).

Tim asks (with respect to status of the relationship between GeoAPI and GeoTools)

The first is whether or not this relationship is spelled out somewhere in the documentation, and whether this documentation is up to date. (I gather that this relationship is still constantly evolving.)

Second, which version of the GeoAPI should I be using.

The answer this week comes from Martin Desruisseux; who provided a history of how these projects have interacted.

And yes the answer is in the documentation; and I have updated the page to include Martin's notes on the history.
- http://docs.codehaus.org/display/GEOTDOC/02+GeoAPI

My take on the matter is that the status is strained; but it is a healthy strain beneficial to both projects.

• GeoAPI keeps the GeoTools project honest about being correct (if you are wrong who cares if you made it run?)
• GeoTools keeps the GeoAPI project honest by actually making sure the ideas can be coded (who cares if the idea can be represented if it does not run?)

As for what version of GeoAPI to use: If you downloaded the GeoTools library you will find a geoapi jar included in the mix; if you are using Maven the pom.xml file will make sure you download the correct jar.

How to look up the EPSG code for a CoordinateReferenceSystem

Today's question comes for the uDig developers list; this is a fairly classic problem - shapefile store their CoordinateReferneceSystem definition as a .prj file, containing "Well-Known-Text". How can you look up the "official" EPSG code for a CoordinateReferenceSystem? And why would you want to?

A CoordinateReferenceSystem generated from "raw" WKT:

• Often does not have an EPSG code. These codes are useful to know when working with data from a range of sources. If we can figure out the code we can construct a WMS GetMap request (for a base map layer) that matches the shapefile.
• Often lacks some of the meta-data used when creating a good MathTransform

Here is how to look up an "official" CoordinateReferenceSystem.

1. Construct a CoordinateReferenceSystem based on what you have.
   

   String name = "ED50";
   String wkt =
     "GEOGCS[\"" + name + "\",\n" +
     "  DATUM[\"European Datum 1950\",\n" +
     "  SPHEROID[\"International 1924\", 6378388.0, 297.0]],\n" +
     "PRIMEM[\"Greenwich\", 0.0],\n" +
     "UNIT[\"degree\", 0.017453292519943295]]";
   CoordianteReferenceSystem example = CRS.parseWKT(wkt);
   

2. Find the Identifier for your CoordinateReferenceSystem
   

   String code = CRS.lookupIdentifier( example, true ); // should be "EPSG:4230

3. Look up the official definition for that Identifier
   

   CoordinateReferenceSystem crs = CRS.decode( code );

You will find the official CoordinateReferenceSystem is much better at generating MathTransforms.

CoordianteReferenceSystem wsg84 = CRS.decode( "EPSG:4326" );
MathTransform transform = CRS.findMathTransform(crs, wsg84, true);
Geometry targetGeometry = JTS.transform( sourceGeometry, transform );

If you do have any trouble - set the lenient flag to false, the transform will no longer be as accurate (as WKT by itself does not have enough information to account for datum shifts etc...).

CoordianteReferenceSystem wsg84 = CRS.decode( "EPSG:4326" );
MathTransform transform = CRS.findMathTransform(example, wsg84, false );
Geometry targetGeometry = JTS.transform( sourceGeometry, transform );

Documentation harmed in the making of this post:

• CRS Helper Class (GeoTools User Guide)
• JTS Helper Class (GeoTools User Guide)
  

Which class is used to repsent a bounding box?

Today we have a great question:

I noticed in the GeoTools Javadoc (2.5 branch) the following 5 classes that could be used to represent an envelope: Envelope, Envelope2D, EnvelopeExample , org.geotools.geometry.iso.coordinate.EnvelopeImpl , org.geometry.jts.spatialschema.geometry.EnvelopeImpl

Is it possible these different envelope classes are represented by a
single interface that I could reference in my code, or do I need to
pick one? Could we refactor these 5 different classes into a single
Envelope2D class/interface?

The answer is a bit of a pain; but it does go a long way toward explaining what we are about with a spatial library, and why GeoTools may be considered difficult to learn.

Is it possible to have a single interface?

In short there is one interface that represents an "Rectangle" well:
- Envelope - this is a GeoAPI interface defined according to the the ISO 19107 Geometry specification

The Envelope interface stores a CRS and a range of valid values for each axis mentioned by the CRS. If you are really sure you are working with a 2D CRS you can make use of a BoundingBox subclass.

But in actual fact you will need to consider a couple other interfaces:
- When working with Java you will need to use a Rectangle, specifically Rectangle2D.Double
- When working with the JTS Topology Suite you will need to use an Envelope class (defined according to the Simple Features for SQL Specification)
- If you are working with Java3D you will find it has its own Bounds and BoundingBox (and BoundingSphere) classes
- And so on ....

Do I need to pick one?

So yes you need to pick one for your application; the GeoTools library will do its best to work with your needs.

Could we refactor these into a single Envelope2D class/interface?

Internally GeoTools often makes use of a single implementation:
- ReferencedEnvelope

The ReferencedEnvelope is one of the first GeoTools specific classes documented in our user guide, and is an example of something that makes the library unique.

Literally RefernecedEnvelope is a compromise:
- ReferencedEnvelope extends JTS Envelope
- RefernecedEnvelope implements GeoAPI BoundingBox

This gives you the best of both worlds; access bounds in a form acceptable to the JTS Geometry classes (which only wory about the numbers), that also address the need of the GeoTools library to track the Coordinate Refernece System (so we know what the number mean).

Documentation Link

Here is the user guide page that talks about this stuff.

How hard can it be?

One of the fun things that happens when working on a project like uDig is people expect you to live up to the name (ie User-friendly desktop Internet GIS).

This post is about living up to the User-friendly part, for the last week or so I have been helping a user place a 400 meter buffer around some points and road networks and generate a PDF.

How hard can that be?

• The point data was found in a Microsoft access database...
  Final solution was to export from Access to CSV and use gdal to convert that to a shapefile and load the shapefile into uDig.
• The projection is kind of lost to the mists of time...
  This is actually a very common occurrence - those who collected the data knew what they were measuring, but for us that come later it results in no end of fun.
  Final solution was to guess based on some shapefiles and adjust the CRS settings until it lined up.
• Placing a buffer around the points was done by using the Reshape operation to generate a new set of features. While figuring out the buffer( the_geom, 400 ) syntax was not too bad it took a little bit of work (and checking the CRS) to see that the data was measured in meters.
  
• Exporting to a PDF can be done...
  But the functionality is hidden as part of the Export Image wizard (PDF is one of the options just like PNG)
  

Lessons learned:
- CSV happens; I should stop treating it as a toy example for developers and build it into the application
- Showing a the raw WKT definition of a CoordinateReferenceSystem is actually useful; and allowing users to edit it even more so.
- Stay visual: The reshape operation just generated a new scratch layer and adds it to the catalog. Not so good - and hard to tell if anything was actually done ... so When the user is working on the Map, they expect the results on the Map,
- PDF really needs its own wizard.

So how (with all of that) can uDig be considered friendly? Well the documentation was updated as we went through the problem; and the developers were on the #udig IRC channel to answer questions.

Documentation harmed in the making of this post:
- Processing the Geometry in a Shapefile (now with a buffer example)
- Map to Image Wizard

Welcome to How 2 Map

This is a continuation of my blog over at java.net. While Java.net is a great way to contact the Java crowd the set up is a little too formal, clunky and language specific for a lot of what I talk about. The recent deluge of spam comments has finally pushed me to move on.

I have kept a blog very in-frequently; but I have been doing a lot of writing. To start off this blog I wanted to cover the kind of writing I am willing to do on the web; and see if I could work that into a useful article / publication / web-log thing that would be interesting enough for others to follow.

• Email: I write a lot of email, sometimes very detailed and researched, sometimes quick (and in my limited opinion funny).
  Email can occasionally be turned into a good blog post, but usually they make a good topic for an article (since you need to fill is so much context
  
• Documentation: I have taken to writing documentation, and sending email links, rather than directly taking part in the geotools user list or udig user list.
  Problem is it seems only I know what has been written, in fact the best way for me to tell if the documentation is successful is to watch what kind of questions are asked on the user list. Last year at this time all the questions were about connecting to WFS or opening a Shapefile, this year there are lots of questions about drawing maps. Looks like the documentation on working with data is starting to work...
  

What I am not going to do is write big long articles; while these can be very valuable - the time is better spent on coding or documentation.