Pages

Saturday 23 April 2011

yadda yadda

I went looking in nabble for an email today; and saw a very interesting link at the top of the page: People.

NameRegistieredPostCount
Frank WarmerdamUnregistered8392
GRASS GISUnregistered8202
JIRA jira@codehaus.orgUnregistered7435
Glynn ClementsUnregistered6480
Jody GarnettUnregistered5511
svn_geotoolsUnregistered5397
Markus Neteler-3Unregistered5322
aaimeRegistered5078
aaime-2Unregistered5044
Michael BartonUnregistered4997
HamishBUnregistered4990
Justin Deoliveira-4Unregistered4427
jody.garnettRegistered3908
Markus NetelerRegistered3891
Justin DeoliveiraUnregistered3802
hamish-2Unregistered3709
Christopher Schmidt-2Unregistered3605
Jason BirchRegistered3517
Paolo CavalliniUnregistered3139
Glynn Clements-2Unregistered2750

Really shows Frank for the community leader he is :-) Although I am not sure what is up with people appearing more than once (perhaps when they switch company / email address).

Tuesday 19 April 2011

Documentation Links

This blog is devoted to documentation; and today marks an interesting turn over point. Changing the User Guide link to point to generated content, and no longer point to the wiki. This is the second "oh that did not work out then" blog post for me this year.

The common thread for both these shifts is taking responsibility for project activities; and no longer relying on the good will of others.

In the case of the wiki, confluence was a great tool that offered really good integration with Jira (which is an excellent issue tracker). And I would like to thank CodeHaus for hosting these services for the project.

The difficulty is that Confluence (with many high profile projects on CodeHaus) became a target for automated attacks and vandalism (the good will of others indeed). Some of the heroic efforts CodeHaus took to combat these problems placed a burden on participation which severely curtailed community participation.

If you look at our page for edit instructions it currently has the following.


Everyone is welcome to edit this wiki; but we need to ask you to sign in first.

1. Sign up to Confluence
2. Sign up to CodeHaus
3. Confirm your Personal Details lists your Confluence Username from step one

You can now join the GeoTools project:

1. Navigate to the GeoTools Project
2. And click on Apply to join as a developer
3. You will need to wait for approval

And finally edit any page on this wiki:

1. To edit any page choose News Operations > Edit

For more information read up on Confluence and Documentation in our Developers Guide.

Comments (Hide Comments)
Great post...Keep posted.Nice page..

:) <a href="http://www.merchantos.com/">'pos software</a>

Comment: Posted by Alysia Douglas at Feb 14, 2011 22:57


Thanks Douglas, you are a pal.

On the bright side, taking the docs into the GeoTools source code, is looking like it will work out, developers are correcting information (that I gathered from the wiki), and it has already landed a volunteer.

It is my hope that buy making contributing to the documentation an svn activity; it will be a short hop from there into code contributions.

Monday 11 April 2011

Classifiers and ColorBrewer

The docs for GeoTools 8 continue to come together; I have been sending a constant stream of tweets out as different pages make it out of the grinder. In terms of progress I have escaped the confines of the core library, but that is the tale for another day.

Today I finished up the documentation for gt-brewer.
Documentation harmed in the making of this post:
  • Classifier - added several examples including how to make them by hand rather than from a feature collection
  • FeatureCollection - updated the classification functions to list all the different options available
  • ColorBrewer - step through from website, palette selection through to generation of an style
Wiki
As is often the case the wiki page I am starting from was:
a) written by me (so is of dubious quality)
b) was cut and pasted from the gt-user list
c) contains a single code example
d) which was being used to quickly answer a question

So the detective work is to sort out what the code example was trying solve and provide some context explaining what is going on and how it works.

For today we had two key concepts Classifier and ColorBrewer.

Classifer
Captures a group of values (either expressed explicitly or as a range) providing a title to each group
classifier.PNG

ColorBrewer
Combination of ColorBrewer and StyleGenerator can be used to generate a FeatureTypeStyle according to your instruction.
ColorBrewer.PNG


This builds on the excellent website http://colorbrewer2.org/ which defines the above palettes for use.
cbrewer.png

Tuesday 5 April 2011

Before and After

I have been having a solid couple of months updating the geotools docs from a wiki - to sphinx. I thought I would share a couple of before and after examples with you.
If you are interested in keeping pace with this documentation effort you can review my twitter feed; it seems that is all I use it for.
Versioned
Right off the bat we can see progress in the form of a latest and stable user guide matching a specific version of GeoTools. This will allow developers to grab a hold of the docs for the version of GeoTools they are using (I still get questions and bug fix requests from GeoTools 2.1 in 2003 ).

BEFORE
Wiki User Guide (examples ranging from GeoTools 2.1 through to 2.7)

AFTER
Latest User Guide (work in progress from 2.8-SNAPSHOT)
Stable User Guide (matching latest 2.7.0 release)


Diagrams

BEFORE
Our initial meet the library page included this rather bright and cheerful graphic.

The problem was this graphic was drawn with viso (hardly an open source tool); more to the point it could not be updated as new functionality was added to the library.

We also had a few class diagrams done with random tools.


AFTER
The new welcome for geotools overview offers a nice sedate graphic.
../_images/geotools.png
The interesting thing is it is now drawn with InkScape as an SVG file and included in the source code. So hopefully others can edit it.

I have also been able to commit ObjectAid diagrams into the code base. These are live diagrams generated by dragging your source files onto the page from within eclipse. They also have an auto image setting so the diagrams can be updated as your classes change.
../../../_images/SimpleFeatureLocking.PNG
The up side of this is more diagrams in the docs; and that the diagrams will be up to date.

Code Examples
One of the big changes (and motivations) behind using sphinx rather than a wiki was the ability to use live code examples in the documentation.

BEFORE
Here is an example from the wiki (Hint it does not actually compile):
private synchronized static FeatureSource
buildMemoryFeatureSource(FeatureCollection coll, String typename,
FeatureType currentFeatureType, AttributeType newTypes[]){

  FeatureType ftState=null;
  MemoryDataStore MStore=null;

  try {
                    MStore = new MemoryDataStore();
                    //---- current attributes
            AttributeType currentTypes[] = currentFeatureType.getAttributeTypes();
            
            //---- new array of attributes = current array+ new attributes
            AttributeType typesNew[] = new
AttributeType[currentTypes.length+newTypes.length];
            
            for(int i=0;i<currentTypes.length;i++){
                typesNew[i] = currentTypes[i];
            }
            for(int i=0;i<newTypes.length;i++){
                typesNew[currentTypes.length+i] = newTypes[i];
            }
                        
            ftState = FeatureTypeFactory.newFeatureType(typesNew, typename);

            MStore.createSchema(ftState);

            
            Iterator iterator = coll.iterator();
            FeatureCollection newColl = FeatureCollections.newCollection();
            Feature feature, newFeature;
            Object[] objs;
            
                    try {
                    for( int count=0; iterator.hasNext(); count++) {
                       feature = (Feature) iterator.next();
                       objs = new
Object[feature.getNumberOfAttributes()+newTypes.length];
                   
                         for (int i = 0; i < feature.getNumberOfAttributes();
i++) {
                            objs[i] = feature.getAttribute(i);
                         }
                    
                         newFeature = ftState.create( objs, feature.getID());
                    
                         newColl.add(newFeature);
                      }
                       } finally {
                           coll.close( iterator );
                       }
    
            MStore.addFeatures(newColl);
            
           return MStore.getFeatureSource(typename);
            
    } catch (Exception e) {
    e.printStackTrace();
    } 
    return null;
}

AFTER
And after we have something that we know compiles and has had the eclipse auto formatter take a run at it for readability.
SimpleFeatureSource alter(SimpleFeatureCollection collection, String typename,
        SimpleFeatureType featureType, final List<AttributeDescriptor> newTypes) {
    
    try {
        
        // Create target schema
        SimpleFeatureTypeBuilder buildType = new SimpleFeatureTypeBuilder();
        buildType.init(featureType);
        buildType.setName(typename);
        buildType.addAll(newTypes);
        
        final SimpleFeatureType schema = buildType.buildFeatureType();
        // Configure memory datastore
        final MemoryDataStore memory = new MemoryDataStore();
        memory.createSchema(schema);
        
        collection.accepts(new FeatureVisitor() {
            public void visit(Feature feature) {
                SimpleFeatureBuilder builder = new SimpleFeatureBuilder(schema);
                
                builder.init((SimpleFeature) feature);
                for (AttributeDescriptor descriptor : newTypes) {
                    builder.add(DataUtilities.defaultValue(descriptor));
                }
                
                SimpleFeature newFeature = builder.buildFeature(feature.getIdentifier().getID());
                memory.addFeature(newFeature);
            }
        }, null);
        
        return memory.getFeatureSource(typename);
        
    } catch (Exception e) {
        e.printStackTrace();
    }
    return null;
}

Ease of Use

Another obvious change as I go through the docs is the strides made to make development easier. From utility classes such as DataUtilities, JTS and CRS through to helpful base classes.

BEFORE: AbstractDataStore
This class was the base for our initial GeoTools 2.0 DataStore API; as such it grew all kinds of interesting tricks as it came to be all things to all people.
../../../_images/AbstractDataStore.PNG
I have left off several classes from the above diagram to protect the innocent.

AFTER: ContentDataStore
Justin and I made a new start with ContentDataStore focused on only asking developers to do the bare minimum needed to support their data format.
And handling all the DataStore, FeatureSource / FeatureStore / FeatureLocking, FeatureCollection/FeatureIterator, FeatureReader / FeatureWriter stuff for them with no additional subclassing.
../../../_images/content.PNG
Details only a developer could love:
  • Previously AbstractDataStore was the subject of a tutorial on the wiki; that carefully walks you through creating six classes needed to read and write a simple text file.
  • We can get a working implementation in four classes this time out and a lot less code.
  • BEFORE: Content was handled through a careful applied series of "wrappers" (ie 30 lines of boilerplate code you had to cut and paste exactly right)
  • AFTER: configure a few settings describing what your format supports out of the box (such as filtering). GeoTools will proceed to do the rest of the work for you (transactions, locking, reprojection).