• As Background
• In a grid
• As agent's aspect
• Example

As Background

To use an image only as a background of the simulation, in a passive way, we only write that we want to display it in the output section of the model:

output {
   display HowToImportRaster {
      image name: 'Background' file:'../images/mnt/mntsect211.png';
   }
}   

In a grid

To use the data contained in the image (in particular the pixel color in a raster image), we need to transform the image in a matrix in order to manipulate it. Afterwards we can create a grid environment using this matrix in order to ease the interactions between other agents of the simulation and the image (via the grid).

The transformation from the image to the matrix is made automatically in GAMA with the operator as_matrix. Note that as_matrix takes a Point as right operand; this point specifies the number of rows and columns of the matrix):

global {	
   var mapColor type: matrix ;
			
   init {
      set mapColor value: file('../images/mnt/mntsect211.png') as_matrix {10,10} ;
   }
}

The above code transforms the image located at '../includes/mnt/mntsect211.png' in a 10x10 matrix of colors.

When a matrix cell includes more than one pixel of the pixel, the average of the pixels color is affected to the cell.

Next we create the grid using this matrix to initialize the color of each cell:

global {	
   var mapColor type: matrix ;
			
   init {
      set mapColor value: file('../images/mnt/mntsect211.png')   as_matrix {10,10} ;
      ask target: cell as list {		
         set color value: mapColor at {grid_x,grid_y} ;
      }
    }
}

environment {
   grid cell width: 10 height: 10;
}

Note that the grid and the matrix must of course have the same dimensions: each grid cell takes the color of the corresponding matrix cell (representing the image).

It is now easy for agents to use image information. For example, if we want an agent to be located on white places of the image, we can write:

entities {
   species izard {	
      init{
         set location value: one_of(cell as list where ( each.color = rgb('white')) ) ;
      }		
   }
}

As agent's aspect

A nice way to represent an agent is to use an image. For this purpose, we need to add an aspect subsection in the species definition.

entities {
   species izard {	
      init{
         set location value: one_of(cell as list where ( each.color = rgb('white')) ) ;
      }	
      aspect image{
         draw image: '../images/icons/izard.gif';
      }
   }
}

We then precize that we want to display the agent with the defined aspect.

output {
   display HowToImportRaster {
      grid cell;
      species izard aspect: image; 
   }   
}

Example

Finally, we present a complete example. We want to import an MNT (Modèle Numérique de Terrain or Digital Elevation Model) data into the simulation and randomly locate some izard agents in the most elevated places of the area (i.e. in the white places of the MNT).

We detail in the following the various sections of the model.

model HowToImportRaster

We first initialize the grid and create the izard agents

• we use the as_matrix operator to transform an image file into a matrix of colors
• we then set the color built-in attribute of the cell to the value of the corresponding matrix cell.

Note that the two constants heightImg and widthImg represent the actual size of the raster image in number of pixels. With the factorDiscret parameter, the user can change the discretization factor to have a more or less fine grid. It is (for the moment) technically impossible to have a factorDiscret of 1 because it would create a grid with more than 30 millions of cells.

We create a grid as environment with the same dimensions as the matrix in which we want to store the image.

Note that the height (resp. the width) of the grid corresponds to the number of rows (resp. of columns) of the matrix:

• in the creation of a matrix: as_matrix {widthImg/factorDiscret,heightImg/factorDiscret} ;)
• in the creation of the grid: grid cellule width: widthImg/factorDiscret height: heightImg/factorDiscret;

global {	
   // Constants
   const heightImg type: int init: 5587;
   const widthImg type: int init: 6201;	
	
   // Parameters
   var mntImageRaster type: file init: '../images/mnt/mntsect211.png' parameter: 'MNT file' category: 'MNT' ;
   var factorDiscret type: int init:20 parameter:'Discretization factor' category:'Environment';
   
   var nbIzard type: int init: 25 parameter: 'Nb of Izards' category: 'Izard';
   var izardShape type: file init:'../images/icons/izard.gif' category: 'Izard';
	
   // Local variable
   var mapColor type: matrix ;
			
   init {
      set mapColor value: mntImageRaster as_matrix {widthImg/factorDiscret,heightImg/factorDiscret} ;
      ask target: cell as list {		
         set color value: mapColor at {grid_x,grid_y} ;
      }
      create species: izard number: nbIzard; 
   }
}

environment {
   grid cell  width: widthImg/factorDiscret height: heightImg/factorDiscret;
}

Izard agents that have been created in the global section are located on one random cell among the list of empty cells (empty(each.agents)) and with a white color (each.color = rgb('white')).

entities {
   species izard {	
      init{
	 set location value: one_of(cell as list where (empty(each.agents) and each.color = rgb('white')) ) ;
      }		
      aspect basic{
     	 draw shape: square color: rgb('orange') size: 1;
      }
      aspect image{
	 draw image: izardShape.path;
      }
   }
}

We finally display:

• the grid
• the original MNT image as background
• izard agents

We can thus compare the original MNT image and the discretized image in the grid. For cosmetic need, we can choose to not display the grid.

output {
   display HowToImportRaster {
      grid cell;
      image name: 'Background' file: mntImageRaster.path;
      species izard aspect: image; 
   }   
   inspect name: 'Species' type: species refresh_every: 5;
}