Docs: the active region

Since our migration towards the udig community I've been struggling around mostly with two concepts that didn't fit exactly into the picture of the existing udig:

• the active region concept
• the GRASS workspace
  

While the second is not yet solved in my mind, the active region concept has come to its (hopefully) final version.

Let's go through it:

1) what is the active region (AR)?

The AR is a defined portion of the territoy inside which calculations can be performed. It is defined by a bounday (n,s,w,e) and a particular resolution (in both northern and eastern directions) and a number of rows and columns, that are directly bound to the resolution (rows and columns can be only integer numbers, so the resolution has to recalculated if the boundary calculus with the resolution doesn't gain integer rows and cols).

The AR concept is particularly useful for example when you have very large maps that don't even fit in you pc's memory and you want to do calculations on a smaller portion of the map or on the whole map, but with lower resolution. In these cases the AR can be set to a particular portion of the map or the resolution can be lowered and the models and algorythms from that moment on will do calculations only on that region, as if the map was contained only inside of it.

2) How to use the AR?

The AR is visually displayed by the Active Region Graphic, which can be found in the catalog view with the other mapgraphic objects.


Once you drag that object onto the map, the first time you will be asked for the mapset you want to use the active region from (for informations about what a JGrass workspace-location-mapset-etc is, have a look here).




Once choosen one mapset, the active region magically appears.


From that moment on an AR definition occurred and every algorythm and module that needs it can retrieve it and use it. The user doesn't have to care, it is the developer's care to include this concept in the calculation models.

3) setting the AR

There are two ways to set the active region.

a) setting the AR by its properties panel

The AR properties panel is rather straight forward. You can set the mapset from which to take the AR from, but please pay attention about the fact that the AR is consistent with the maps you are working on, i.e. don't use maps from different mapsets or locations, since you could gain very fancy results :) Always the same thing: always try to know what you are doing.

You can set boundaries and resolutions. Resolutions are recalculated everytime to be in shape woth the rows-cols consistency.

You can also set some style proprties, like color and transparency.

And last but not least you can also set the region to a particular map, raster or vector. in the case of a raster map, its fileregion (i.e. its boundaries and resolution) is taken and the AR is set to that. In the case of a vector map the region is set to its boundary, but then, since vector maps do not have a resolution definiton, the region is adjusted to snap its boundaries and resolution to the prior AR. This is mandatory to be able to coninue to work on a consistent way on the raster grid.




b) setting the AR by the box tool

The second way to set the AR is the Active Region tool that can be found in the toolbar. At the moment of writing it has the same icon of the selection tool, I hope to find some time to change it soon.



With this tool you will be able to just draw a box and the active region will be set to that box. In fact the selected box is adapted to snap to the prior AR and naturally will have the resolution of the prior AR.