Introduction to vector data

When we produce a shapefile with dedicated software or get such data from external ressource, we often get several files. Here are the files that are mandatory for the importation in GAMA:

.shp: this file contains the geometric shapes
.shx: this file contains the shape index format; a positional index of the feature geometry to allow seeking forwards and backwards quickly
.dbf: this file contains the attribute table

Note that a .prj file is often provided with the shapefile. This file contains information about the coordinate system and projection of the shapefile. In the context of data expressed in a Geographic Coordinate System (longitude, latitude), GAMA will automatically try to applied the adequate UTM (Universal Transverse Mercator) projection in order to express the coordinate of the object in meters.

How to create agents from the shapefile

In order to import a shapefile and use its data, we will create agents that will be instantiated with the geometry and the attributes of the elements of the shapefile: each point, polyline and polygon of the shapefile will become an agent in GAMA. We consider that each layer of the GIS (i.e. each shapefile) contains elements that can be represented by only one species of agent. For example, if we want to import data of the buildings of a city and of its streets, we will import two different shapefiles: one containing buildings and the other one the streets.

In this part, we plan to import the data of the water management units of the Adour-Garonne basin.

We thus begin by creating a new agent species:

entities {	
   species ManagementUnit{
      aspect basic{
         draw shape: geometry;
      }
   }	
}

We create as many instances of ManagementUnit agent as there are geometric elements in the shapefile:

global {
   var ManagementUnitFile type: file init: '../images/ug/UGSelect.shp';
	
   init {
      create species: ManagementUnit from: ManagementUnitFile.path ;
   }
}

It is important to note that the environment is by default a 100x100 square. In most of the shapefiles, this space is not adapted to display the shapes. We thus have to fix manually the bounds of the environment. When we only use 1 shapefile, we can use this file to bound the environment: GAMA will consider the minimal bounding rectangle of the data contained in the shapefile and fix the bounds of the environment with its dimensions.

environment bounds: ManagementUnitFile.path;

We can then display the created agents as usual:

output {
   display HowToImportVectorial {
      species uniteDeGestion aspect: basic; 
   }
   inspect name: 'Species' type: species refresh_every: 5;
}

How to import attributes data from the shapefile

The shape built-in attribute of the agents created using the shapefile (ManagementUnit agents in the example) gets automatically the geometry of the corresponding geometric element of the shapefile.

But the geometric elements of the shapefile can have additional attributes. To get them in the created agents, we need to:

Add additional attributes to the agent
Assign each agent attribute by reading the corresponding attribute in the shapefile.

In the example, we thus add three additional attributes. These attributes must have the same type as the attributes in the shapefile:

entities {	
   species managementUnit{
      var MUcode type: int;
      var MULabel type: string;
      var pgeSAGE type: string;
	
      aspect basic{
     	 draw shape: geometry;
      }
   }	
}

The reading of these attributes is made during the creation of the agents. 'Code_UG', 'Libelle_UG' and 'PGE_SAGE' are the names of the different attributes in the shapefile.

global {
   var ManagementUnitShape type: file init: '../images/ug/UGSelect.shp';
	
   init {
      create species: managementUnit from: ManagementUnitShape.path 
         with: [MUcode::read('Code_UG'), MULabel::read('Libelle_UG'), pgeSAGE::read('PGE_SAGE')] ;
    }
}

How to use shapefile as background

We can also use a shapefile as background of the simulation display. It becomes then a passive image (GAMA does not create any agent). Note that we have to use the gis: keyword to import a shapefile instead of the file: keyword used for raster image.

output {
   display HowToImportVectorial {
      image name: 'GISBackground' gis: ManagementUnitShape.path color: rgb('blue');
   }
}

Complete example

model HowToImportVectorial


global {
   var ManagementUnitShape type: file init: '../images/ug/UGSelect.shp' parameter: 'Management unit:' category: 'GIS' ;
	
   init {
      create species: managementUnit from: ManagementUnitShape.path 
	with: [MUcode::read('Code_UG'), MULabel::read('Libelle_UG'), pgeSAGE::read('PGE_SAGE')] ;
   }
}

environment bounds: ManagementUnitShape.path {}

entities {	
   species managementUnit{
      var MUcode type: int;
      var MULabel type: string;
      var pgeSAGE type: string;
		
      aspect basic{
     	 draw shape: geometry;
      }
   }	
}

output {
   display HowToImportVectorial {
      image name: 'GISBackground' gis: ManagementUnitShape.path color: rgb('blue');
      species managementUnit aspect: basic; 
   }
   inspect name: 'Species' type: species refresh_every: 5;
}

► Sign in to add a comment