Adrian Custer wrote:
Hey All,
On Wed, 2006-03-01 at 13:02 +0200, Jody Garnett wrote:
Adrian I enjoyed your email
and wondered where in the programers guide it could go? Before or after
we introduce the concepts you talk about? Perhaps it could be added as part
of the Overview? How does "4 Guided Tour" sound?
You mean Programer's Guide 1.4? Great. Let's work on that. If you want
it done quickly then we ought to schedule a doc irc afternoon or two
That would be great!
(i.e. one to get started and one to finish). The current problem is that
I see the lack of documentation pretty clearly (i.e. what's needed) but
in order to solve this on my own, it is taking me a huge amount of time
to figure out the various code bases so I'm making slow, unsteady
progress. I realize, of course, that this is not a priority for you all
but unfortunately, I suspect this is a key stumbling block.
Actually it is a priority, but it is on my volunteer time - uDig needs
more developers and easing
the learning curve is the major bottleneck.
To code effectively on uDig I see as needed:
* A good understanding of GIS'es an how they work
I am not sure this one is needed, an understanding of geospatial data
(feature, crs, coverage) would be higher on my list.
* A grasp of the terminology used in the uDig/Geotools stack
* A grasp of Java/C/some programming languge
Java should be sufficient, we would like to support scripting languages
but are not there yet.
* A grasp of the eclipse IDE
This one is tough, hence the importance of that reading list.
* An understanding of the Architecture
Earlier today I sent out a link to the original documentation, this is
may help. And the over view of the system is
still accurate although some of the names have changed.
at least that's what I'm working on acquiring.
Three core elements are needed for explaining the uDig architecture
1) A scalable architecture diagram:
There are a number of useful schematic diagrams of udig and geotools,
for example, the diagrams included in the slide show that was posted to
the mailing list (whose name I forgot because I just deleted the file
yesterday). However, these diagrams are very primitive: they don't, for
example, get used in a more detailed explanation of what classes get
called in different situations. I hope to develop eventually a diagram
that scales from the
Hardware || JVM / Clibs || Geotools / Eclipse || uDig
to a diagram where each uDig and Geotools package can be viewed as a
block with an API used to access that block and an internal example. I
grant this is a long term vision but something I'm working on for my own
sanity in this way complex uDig world. E.g.
**************************************************************
* N * * Api interface 1 * Api interface 2 ... *
* A * *************************************************
* M * *
* E * Code Examples ... *
* * *
**************************************************************
Once I can make a single clean example, I'll convert my hand sketches to
SVG with inkscape and spam the list.
yeah spam - I am still having trouble understanding your ascii art (and
I love ascii art).
I would approach it differently:
1. A code example for a specific task
2. A block diagram of the software stack with the packages involved
highlighted
I have started two geotools documentation projects already, and have
been forced to
wait as the API was made consistent. It is a tradeoff we fighting
stability vs usability.
2) A diagram of the data model of a uDig in a frozen state:
uDig follows the model, view, controller split. I would like a diagram
of each for a uDig frozen at the moment when it has 2 Projects open, one
with 5 maps, with one map having n different layers (possibly one of
each type of IGeoResource which uDig provides.
That can be done, although there is often more then one "view" hitting
the model. You may
do best to consider the layer view first, and then treat rendering after.
The idea is to have a hypothetical tree of how to access each of the
components in the model (data) hierarchy, in the view hierarchy, and in
the controller hierarchy. Since there are static methods provided to
access the root of each hierarchy, the three trees would provide users
with a cannonical example for accessing each piece of a running uDig.
You may find the data access guide (on that GeoConnection Resrouces
page) a useful starting place.
For example, right now I'm trying to build a uDig layer from
scratch. Now I have to figure out where the CRS (or SRS, I'm not
yet sure of the semantic distinction) information is held. I can
imagine that the map must have its own and each feature (or
maybe geometry) has its own or maybe all the features in a
datasource always share the same. I.e. I know that the CRS's
must be defined at various levels but we don't yet have a
diagram that shows:
This example is off the top of my head. It's not worth
my time right now to get accurate. Think of it as an
example of some other system.
uDigMap:
--- getCRS ---> The Map's CRS
Map -> ViewPortModel -> CRS
--- resolve IGeoResource 1 ---> Feature 1.getCRS()
IGeoResrouce -> FeatureType -> GeometryAttribute -> CRS
or
IGeoResoruce -> IGeoResourceInfo -> CRS
(need to check the last one)
--- resolve IGeoResource 2 ---> Feature 2
GeoResource -> IGeoResourceInfo -> CRS
I am now sure since a WMS layer would also need to report its CRS.
3) A set of examples of how to construct each element.
Access is one thing, but construction is another. Once we have diagrams
for accessing an example of each piece in uDig we then need an example
of how to *build* from scratch each of the pieces. The building from
scratch is a second way of sharing the model with new programmer's.
I tend to keep these at the javadoc level as part of the class javadoc.
While the "resolve" idea is quite simple in the resolution direction,
I'm still quite puzzled about what's going on when we create a new
coordinate, geometry, feature, datastore (magic happens here)
IGeoResource eventhough I can now display my buffered points in a map.
Fair enough, let me know how the existing pictures in the programers
guide did for you. I was worried
I went into too much detail. There is a balance, when introducting a
construct sticking to use is usually
the best, if I put in too much explanation the how to use things becomes
less clear.
For example, I suspect the FAQ "How do I build a Layer programatically"
is exactly this question and is *not* answered at all by the current
answer. For me the question is "how do I start with java doubles and
build up the pieces so I end up drawing a georeferenced map, say a
triangle with vertices in Paris, London and Moscow?" I'd like to create
a really well commented file that explains with a full paragraph each
step of the process, and ideally that then gets expanded into examples
that do each step slightly differently.
There are two reasons you are having trouble:
1. You are the first person to do it
2. We are having to dredge up our original design and fill in the bits
for you
Creating new content entirely from scratch happens less often then one
would expect. Indeed uDig 1.1 will
be the first stable release allowing a non programmers to define new
content.
For a good documentation stack, I suspect we should have these three
elements: a scaleable architecture diagram, an example of each M/V/C
tree, an example of building each component. I suspect that getting that
into one's head is the precursor to being effective at all in uDig
development (along with understanding well how the eclipse IDE works and
where each of the ten million preferences actually hangs out).
Unfortunately, without yet knowing this and having it in *my* head, I
can't sit down and do the work to make the diagrams.
Okay, back to trying to figure out uDig so I can write some docs for it
and start developing the analytic components.
Should we grab a new wiki space for this so we can be a bit more brutal
in our editing?
Jody
_______________________________________________
User-friendly Desktop Internet GIS (uDig)
http://udig.refractions.net
http://lists.refractions.net/mailman/listinfo/udig-devel
