Getting started: Using Python with ILWIS

From ILWIS
Jump to: navigation, search
Main Page Arrow.png Getting started Arrow.png
Download Installation guide Starting ILWIS Displaying spatial data Displaying tabular data Viewing metadata Executing operation Using Python console Settings Using Python with ILWIS
Python installation

Python installation
Python is an open source programming language used in the new ILWIS; replacing the scripting language of previous versions. Via Python console situated in the new ILWIS main window, the Python interpreter can import automatically whole ILWIS functionality which allows users to write high level scripts for multi-source geoprocessing. The Python interpreter and its extensive standard library are included in ILWIS, so no need for separate installation. You may also install Python program independently and still import ILWIS objects and functionalities and implement ILWIS raster and vector operations via Python editor (IDLE). However, since the Python is not fully integrated in this beta version, you should install Python independently if you like to make extensive use of it. Python interpreter and library are freely available in source or binary form e.g., http://www.python.org . Procedures for installing Python are:

Mar.jpg
  • Download 32 or 64 bits(depending on your system configurations) Python 3x installer from: https://www.python.org/downloads
  • Start the installer wizard(the Python version has to be the one supported by ILWIS)

IDLE (Python GUI) might be useful if you have no other Python IDE installed. IDLE is included in abovementioned installer, when choosing the default installation. In order to use Python with ILWIS, you also need to download and install ILWIS Objects extension for Python:

Mar.jpg
  • Download the ILWISObjects for Python3.x executable file from: https://github.com/52North/IlwisCore/releases
  • Follow the ILWIS Objects install wizard, you will be asked to select the Python installation directory, to configure the extension
Python for ILWIS
More information on this topic is available on: ILWIS Python API Tutorial

Python for ILWIS
The following description is based on use of Python interpreter independently. The use of ILWIS Python console will be described in later stage.
To start the Python:

Mar.jpg
  • Double click on IDLE icon on your desktop
  • Or from Windows start tab, select ”All Program”
  • From the list select “Python”
  • From the opened list click the IDLE icon

The IDLE shell window will be opened. This shell allows you to type Python commands or to create a Python scripts file and save it for repetitive use. In order to use ILWIS objects with Python, you need to import them first. To do that, type at the prompt of the Python shell/IDLE:

 import ilwis 

This imports the ILWIS library called “ilwisobjects” and assign the alias ilwis to it. In case, you have your data in one directory, for the convenience define your working catalog (directory) for farther use. This can be done by typing the following at the IDLE prompt:

ilwis.Engine.setWorkingCatalog("file:///C:/my directory")

The content of the string “C:/my directory“ has to be modified in order to refer to your drive and directory where you have your data. If the path is not correct no data will be loaded and no warning will be given. The script bellow shows examples of number of commands required to derive information from a polygon map. You can use your own polygon map and its attribute table and adapt this commands to derive information from the map and its attribute table. In this example, a polygon map called “countries” and its attribute table is used.

 import ilwis
 ilwis.Engine.setWorkingCatalog("file:///C:/my directory")
 world = ilwis.FeatureCoverage("countries.shp")
 table = world.attributeTable() 

Via aforementioned commands you have imported the polygon map “countries” and its attribute table to Python environment with variable names “world” and “table” respectively. Use the following commands to derive information related to this polygon map and its attribute table.

 world.featureCount()			  # Gives number of polygons  
 world.type()				  # Displays the map type 
 world.coordinateSystem().name()	  # Gives the name of the coordinate system file 
 print(world.envelope())		  # Displays coordinates of the map (min/max X, Y)
 table.columnCount()			  # Gives number of columns 
 table.columns()			  # Displays names of the columns
 len(world.attributeTable().columns())	  # Displays number of columns
 table.recordCount()			  # Gives number of the records
 table.record(4)			  # Displays the records contents 

Use the following commands to import a raster map to Python and to derive information concerning the raster map. In this example, a raster map called “soil” is used. The file has ILWIS previous format.

 
 raster=ilwis.RasterCoverage("soil.mpr")  # Loads the raster map and assign the alias raster 
 raster.name()				  # Displays the name of the loaded map
 raster.type()				  # Gives the map type
 raster.domain()			  # Displays the name of the domain 
 raster.size().xsize			  # Gives number of columns in the map 
 raster.size().ysize			  # Displays number of rows in the map
 raster.coordinateSystem().name()	  # Gives the name of the coordinate system file
 raster.geoReference().name()		  # Displays the name of the georeference 
 print(raster.envelope())		  # Displays coordinates of the map (min/max X, Y)
 raster.pix2value(ilwis.Pixel (0, 0))	  # Gives the pixel value at the defined location
 raster2=raster/2 (value domain)	  # Divides the pixel values of the map by two  
 
An example of Python with ILWIS

An example of Python with ILWIS

Figure 1, The IDLE editor; it is used for developing applications or writing scripts

For this exercise, you need to download the hello world zip file “ILWISObjects-HelloWorld.zip”. The ILWISObjects-HelloWorld.zip archive contains the Python script (helloworld.py), plus the ILWIS3 feature dataset of the world countries. This data set is used to illustrate the use of Python in ILWIS. If you have not downloaded the file yet, you can download it from:

Mar.jpg

Once the Python is installed, the IDLE shell can be opened by:

Mar.jpg
  • From Windows start tab, select All Program
  • From the list select Python
  • From the opened list click the IDLE icon

The IDLE shell window will be opened (Figure 1). This shell allows you to type Python commands or to create a Python scripts file and save it for repetitive use. In order to use ILWIS objects with Python, you need to import them first. To do that, type at the prompt (command line) in the Python shell:

import ilwis 

This imports the ILWIS library. In case, you have your data in one directory, for the convenience define your working catalog (directory) for farther use. This can be done by typing the following at the IDLE shell prompt:

 # To set the path to any locations, URL or local:  
 ilwis.Engine.setWorkingCatalog("file:///C:/my directory") 
 # To set the path to your local drive:
 ilwis.Engine.setWorkingCatalog("C:/my directory>")         
 # To use "\" instead of "/"
 ilwis.Engine.setWorkingCatalog(r"file:\\\C:\my directory") 

The content of the string C:/my directory has to be modified in order to refer to your drive and directory where you have your data (e.g. directory where you have the HelloWorld data). If the path is not correct no data will be loaded and no warning will be given. So, it is important to make sure that the path to working catalog is correct. The ILWIS data format includes multiple files containing either meta or binary data, just like the ESRI Shapefile format. The multi-polygon geometries representing the world's countries are stored in countries.mpa and countries.mpz# for metadata and the binary data respectively. The feature attributes like name, population, etc. are stored in (attribute-)table files called countries.tbt (metadata) and countries.tb# (binary data). In ILWIS and in Python scripts, each dataset is called by the metadata file name. The script bellow shows number of commands required to derive information from a polygon map. You can use your own polygon map and its attribute table and adapt this commands to derive information from the map and its attribute table. In this example, a polygon map called countries and its attribute table is used. The following script can be used to derive attribute information:

 import ilwis
 ilwis.Engine.setWorkingCatalog("file:///C:/my directory")
 world = ilwis.FeatureCoverage("countries.shp") 
 table = world.attributeTable() 

Via aforementioned commands you import the polygon map countries and its attribute table to Python with variable names world and table. Use the following commands to derive information related to this polygon map and its attribute table.

 world.featureCount()                    #Gives number of polygons               
 world.type()                            #Display the map type		         
 world.coordinateSystem().name()         #Gives the name of the coordinate system file 
 print(world.envelope())                 #Display coordinates of the map (min/max X, Y) 
 table.columnCount()                     #Gives number of columns	          
 table.columns()                         #Display names of the columns 			 
 len(world.attributeTable().columns())   #Display number of columns 	         
 table.recordCount()                     #Gives number of the records		          
 table.record(4)                         #Display the records contents 

In addition to type, interactively, Python expressions at the IDLE editor prompt, you can use Python files that contains python codes or scripts allowing to implement computations and manipulation of raster and vector data. In the following example we use the Python file HelloWorld.py to derive attribute information from the polygon map countries.mpa and its attributer data. To view the Python script, please open it in IDLE (Python GUI):

Figure 2, the helloworld.py Python script
Mar.jpg
  • From the IDLE shell Menu bar, select File
  • From the list select Open
  • Select HelloWorld.py from the directory where you have the HelloWorld data
  • Click Open to view the file

The contents of the HelloWorld.py file is shown in Figure 2. As you can see in the second line, the working catalog ("file:///D:/<working>/<directory>") is replaced with the directory where the data is available, in this case; "file:///C:/HelloWorld". To run this script:

Mar.jpg
  • Insert the path (unzipped helloworld data folder) into line 2
  • You need to save the changes before you can run the script, so
  • From menu bar select File and from the list select Save
  • Hit F5 key on your keyboard or
  • From menu bar select Run and from the list select Run module

This script should print the sorted list representing each country abbreviation and population in a rank ordered by its population like:

Country abbreviation Population
CN 1338612970.0
IN 1166079220.0
US 313973000.0
. .
. .
Explaining the Code line by line

Explaining the Code line by line

 1:  import ilwis
 2:  ilwis.Engine.setWorkingCatalog("file:///C:/my directory")
 3:  world = ilwis.FeatureCoverage("countries.mpa")
 4:  population_ranking = {}
 5:  for country in world:
 6:       population_ranking[str(country["iso_a2"])]=int(country["pop_est"])
 7:  Alist= sorted(population_ranking.items(), key= lambda x: x[1], reverse= True)
 8:  print ("Country abbreviation", “\t” , "Populations" )
 9:  for country in plist:
          print(“\t”, str(country[0]) +  2* "\t" + str(country [1])) 

Line 1 imports the ILWIS library.
Line 2 sets the current working catalog to a directory in a local file system, indicated by a URL containing of the protocol prefix file:// followed by a directory path “/C:/my directory”, where the countries data are stored. For a local file system on Windows, the directory can also be specified as for example, C:\my directory. As soon as the working catalog is set, ILWIS scans it for relevant geo-data files, and probes for their metadata. The metadata is remembered in order to speed-up reading and processing later on. In order to recognize catalog items as usable geo-/meta- data, ILWIS internally relies on so called connectors (plugins). Since the standard installation of ILWIS Objects comes with an ILWIS3- and a GDAL-connector, it will detect a large number of vector and raster formats, for example *.shp, *.kml and *.tif as well as their ILWIS3 equivalents *.mpa, *.mps, *.mpp and *.mpr.
Line 3 loads a feature coverage object (FeatureCoverage), which includes all the geo-information about the features contained in the file (in this case countries) and assigned a name “world”.
In line 4, it creates an empty dictionary (to be used later to store population data).
Line 5 implements the standard Python iterator interface to loop over each country in the world.
Line 6 stores the population attribute (country["pop_est"]) as a native Python integer object into the created dictionary “population_ranking using the string (str) typed ISO abbreviation attribute (country["iso_a2"])) as keys.
Line 7 is a very pythonic way of sorting the dictionary population_ranking by converting it to a sorted list of tuples (.items()) using the second part of each tuple as the sort key (key=lambda x: x[1]). The index “x[1]” suggests to use the second column as the key and “reverse = True” indicates to use descending sorting.
Line 8, print titles for the columns.
Line 9, print the sorted data on the screen in two columns; abbreviation for each countries and corresponding population.
Large amount of information on Python application in ILWIS can be found at: https://github.com/52North/IlwisCore/wiki