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:
gitto clone our project template repository:
git clone firstname.lastname@example.org:geotrellis/geotrellis-sbt-template
- Once available, from the root directory of the cloned repo, MacOSX
and Linux users may launch the
sbtscript contained therein; this will start an SBT session, installing it if it has not already been.
- Once SBT is started, issue the
consolecommand; 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
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/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
varies by CellType. In this
case, the use of
IntArrayTile implies an
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
./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
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
<jarfile>, provided you have Spark installed on your local machine. Fat
jars created via
assembly can be supplied as well to
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.