Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wenzeslaus/python-grass-addon

How to write a Python GRASS GIS 7 addon
https://github.com/wenzeslaus/python-grass-addon

addon gis grass-gis ipython-notebook python workshop

Last synced: 23 days ago
JSON representation

How to write a Python GRASS GIS 7 addon

Awesome Lists containing this project

README 

        
# How to write a Python GRASS GIS 7 addon



This material was developed for FOSS4G Europe 2015 workshop.





 GRASS GIS logo





 FOSS4G-E 2015 logo




## How to use this tutorial



### Using only GRASS GIS



Start GRASS GIS on you computer. Browse through IPython Notebooks as rendered on GitHub.

To do this you just need to click on one of the files with the suffix `.ipynb`.

In GRASS GIS in *Layer Manager* window, select *Python shell* in the bottom

to get an interactive Python console where you can input, edit and run the examples.

You may want to make the window bigger to have more space for the code.



### With IPython and Git



Navigate to the directory where you want to work and clone this

repository (unless you already downloaded a copy):



    git clone https://github.com/wenzeslaus/python-grass-addon.git



Navigate to the repository directory:



    cd python-grass-addon



Start GRASS GIS, from command line, using the North Carolina sample dataset:



    grass7



Run (supposing that you are already in a GRASS GIS session) on command line:



    ipython notebook



You will get a website in a web browser where you can select individual Notebooks,

edit and run the examples.



## Abstract



GRASS GIS is a leading software in analysis of geodata, it offers more than 400 modules in its core version plus many addons (i.e., user contributed modules). But what if the tool you are looking for is not present in GRASS GIS? So, simply create your own, we will show you how to do that in this workshop.



In GRASS GIS 7, Python is the default language for creating addons. There are two main Python libraries included in GRASS GIS. Python Scripting Library allows you to perform analysis and compute new data by chaining existing modules to create your own workflow.



With PyGRASS library wrapping the C functions, you can create new data sets (vector and raster) directly through Python calls, increasing considerably the power and performance of your scripts. You can conveniently mix both GRASS Python libraries with other Python libraries like NumPy, or SciPy. In this workshop, we will guide you through the basic steps of writing your own Python scripts, starting with calling and chaining GRASS GIS modules, followed by a more pythonic experience when using PyGRASS to access and modify your data directly.



You will then upgrade your script into an addon by defining a simple interface to enable automatically generated GUI. The next part of workshop will look into more advanced usage of GRASS GIS 7 capabilities, including Python spatio-temporal API to handle time series in your addons, creating your own toolbox with your newly developed addons and finally, introducing the new testing framework you should use as a responsible person to make sure your addons are in great shape.



Don't worry if we won't cover all the topics during the workshop, all materials will be accessible online and GRASS GIS community is always prepared to answer your questions!



## Required knowledge



Participants should have basic knowledge of GIS, basic knowledge of GRASS GIS and basic knowledge of Python.



## Set up a server



When organizing a workshop, it might be advantageous to use a server with IPython Notebook

rather then setting up the environment on participant's computers. When IPython Notebook

is used on a server, participants will need only a browser. All server-side work is easy

to do thanks to Docker.



    mkdir workdir

    cd workdir



    wget http://grass.osgeo.org/sampledata/north_carolina/nc_basic_spm_grass7.tar.gz

    wget https://github.com/wenzeslaus/python-grass-addon/archive/master.tar.gz



    tar xvf nc_basic_spm_grass7.tar.gz

    tar xvf master.tar.gz



Now you can get the basic GRASS GIS image. Note that if you user does not have permissions

to use docker (the usual defaut), you have to prefix the `docker` command with `sudo`. The same applies for scripts used futher on which are using the `docker` command. If you already have the image, you can skip this step.



    docker build github.com/wenzeslaus/grass-gis-docker



To create the image and containers we need some files from this repository (we got its content in previous steps). We use `mv` because we don't need those files to be compied to the containers later.



    mv python-grass-addon-master/Dockerfile .

    mv python-grass-addon-master/run_containers.sh .

    mv python-grass-addon-master/command_containers.sh .



Build a Docker image with sample dataset and Notebooks. If you are using your image for GRASS GIS (see above), be sure you have the right image name in the Dockerfile (used by following command).



    docker build -t wenzeslaus/python-grass-addon .



Create a file with users you want to create an container for. The file must contain

emails at the beginning of each line (it can be for example CSV, double quote at the beginning

is ignored).



    [email protected]

    [email protected]



Now you can start:



    ./run_containers.sh workshop_atendees.txt 9000



Alternatively, you can just specify number of conatiners you want to create:



    ./run_containers.sh 15 9000



This will give you list of URLs and passwords with associated usernames. Usernames are

used only to keep track of containers and to distribute the credentials. Note that

the atendees will have to get through "untrusted connection" dialog in their browsers

because the certificate used is self-signed.



The above command will also create a file named `containers_workshop_atendees.txt`

(or `containers_dateandtime.txt`) with names of conatiners.

For further actions, if they are simple enough,

you can use a prepared script. For example, to get rid of the containers use:



    ./command_conatiners.sh stop containers_workshop_atendees.txt

    ./command_conatiners.sh rm containers_workshop_atendees.txt



## Instructions for participants when IPython Notebook server is used



You have obtained URL which looks like:



    https://fatra.cnr.ncsu.edu:9503



Type it precisely to the web browser including the *s* at the end of

`https`, note also that port number is specified (the number at the end

separated from domain by a colon.



You browser will warn you about invalid security certificate. In this

case, you can safely add security exception. The reason for

the message is that the certificate is self-signed.



Finally, enter the password you were provided with. Then you should

see a list of notebooks as displayed by IPython Notebook.



## When and where the workshop was presented



* North Carolina State Univeristy, test run (2 hours)

* FOSS4G Europe 2015, Como, Italy (4 hours)

* North Carolina State Univeristy, workshop for a geovisualization class (2 hours), [recording available](https://www.youtube.com/watch?v=PX2UpMhp2hc)



## Authors



* Pietro Zambelli, European Research Academy

* Markus Neteler, Fondazione Edmund Mach

* Luca Delucchi, Fondazione Edmund Mach

* Vaclav Petras, NCSU OSGeoREL

* Anna Petrasova, NCSU OSGeoREL



Copyright (C) 2015 by authors.



## License



The documentation is dual licensed under CC BY-SA and GNU FDL.



The code samples are under GNU GPL 2 or later

(which is the license GRASS GIS is under).