Quick Start

For most users, it is not necessary to download the GeoTrellis source code to make use of it. The purpose of this document is to describe the fastest means to get a running environment for various use cases.

Wetting your Feet

By far, the quickest route to being able to play with GeoTrellis is to follow these steps:

git clone git@github.com:geotrellis/geotrellis-sbt-template
  • Once available, from the root directory of the cloned repo, MacOSX and Linux users may launch the sbt script contained therein; this will start an SBT session, installing it if it has not already been.
  • Once SBT is started, issue the console command; this will start the Scala interpreter.

At this point, you should be able to issue the command import geotrellis.vector._ without raising an error. This will make the contents of that package available. For instance, one may create a point at the origin by typing Point(0, 0).

This same project can be used as a template for writing simple programs. Under the project root directory is the src directory which has subtrees rooted at src/main and src/test. The former is where application code should be located, and the latter contains unit tests for any modules that demand it. The SBT documentation will describe how to run application or test code.

Hello Raster, Revisited

On the landing page, an example of an interactive session with GeoTrellis was shown. We’re going to revisit that example here in more detail, using the various parts of that example as a means to highlight library features and to marshal beginners to the sections of interest in the documentation.

It is first necessary to expose functionality from the relevant packages (a complete list packages and the summary of their contents may be found here):

scala> import geotrellis.raster._
import geotrellis.raster._

scala> import geotrellis.raster.mapalgebra.focal._
import geotrellis.raster.mapalgebra.focal._

Much of GeoTrellis’ core functionality lies in the raster library. Rasters are regular grids of data that have some notion of their spatial extent. When working with rasters, one can operate on the grid of data separately from the spatial information. The grid of data held inside a raster is called a Tile. We can create an example Tile as follows:

scala> val nd = NODATA
nd: Int = -2147483648

scala> val input = Array[Int](
     nd, 7, 1, 1, 3, 5, 9, 8, 2,
     9, 1, 1, 2, 2, 2, 4, 3, 5,
     3, 8, 1, 3, 3, 3, 1, 2, 2,
     2, 4, 7, 1, nd, 1, 8, 4, 3)
input: Array[Int] = Array(-2147483648, 7, 1, 1, 3, 5, 9, 8, 2, 9, 1, 1, 2,
2, 2, 4, 3, 5, 3, 8, 1, 3, 3, 3, 1, 2, 2, 2, 4, 7, 1, -2147483648, 1, 8, 4, 3)

scala> val iat = IntArrayTile(input, 9, 4)  // 9 and 4 here specify columns and rows
iat: geotrellis.raster.IntArrayTile = IntArrayTile(I@278434d0,9,4)

// The asciiDraw method is mostly useful when you're working with small tiles
// which can be taken in at a glance
scala> iat.asciiDraw()
res0: String =
"    ND     7     1     1     3     5     9     8     2
     9     1     1     2     2     2     4     3     5
     3     8     1     3     3     3     1     2     2
     2     4     7     1    ND     1     8     4     3
"

Note that not every cell location in a tile needs to be specified; this is the function of NODATA. Also be aware that NODATA‘s value varies by CellType. In this case, the use of IntArrayTile implies an IntCellType which defines NODATA as seen above.

As a GIS package, GeoTrellis provides a number of map algebra operations. In the following example, a neighborhood is defined as the region of interest for a focal operation, the focal mean operation is performed, and a value is queried:

scala> val focalNeighborhood = Square(1)  // a 3x3 square neighborhood
focalNeighborhood: geotrellis.raster.op.focal.Square =
 O  O  O
 O  O  O
 O  O  O

scala> val meanTile = iat.focalMean(focalNeighborhood)
meanTile: geotrellis.raster.Tile = DoubleArrayTile(D@7e31c125,9,4)

scala> meanTile.getDouble(0, 0)  // Should equal (1 + 7 + 9) / 3
res1: Double = 5.666666666666667

In this example, note that the NODATA value was simply ignored in the computation of the mean.

This is only a very simple example of what is possible with GeoTrellis. To learn more, it is recommended that the reader continue on with the core concepts section. Another example geared towards new users is available in the kernel density tutorial.

Using GeoTrellis with Apache Spark

GeoTrellis is meant for use in distributed environments employing Apache Spark. It’s beyond the scope of a quickstart guide to describe how to set up or even to use Spark, but there are two paths to getting a REPL in which one can interact with Spark.

First: from the geotrellis/geotrellis-sbt-template project root directory, issue ./sbt to start SBT. Once SBT is loaded, issue the test:console command. This will raise a REPL that will allow for the construction of a SparkContext using the following commands:

val conf = new org.apache.spark.SparkConf()
conf.setMaster("local[*]")
implicit val sc = geotrellis.spark.util.SparkUtils.createSparkContext("Test console", conf)

It will then be possible to issue a command such as sc.parallelize(Array(1,2,3)).

Alternatively, if you have source files inside a project directory tree, you may issue the assembly command from sbt to produce a fat .jar file, which will appear in the target/scala-<version>/ directory under your current project’s root directory. That jar file can be supplied to the Spark shell as part of the command spark-shell --conf spark.serializer=org.apache.spark.serializer.KryoSerializer --jars <jarfile>, provided you have Spark installed on your local machine. Fat jars created via assembly can be supplied as well to spark-submit commands for running jobs on a remote Spark master. Again, the ins-and-outs of Spark are beyond the scope of this document, but these pointers might provide useful jumping off points.