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:
- Use
git
to clone our project template repository:
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.op.focal._
import geotrellis.raster.op.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
(perhaps derived from geotrellis-sbt-template
), you may issue the
assembly
command from sbt
to produce a fat .jar file, which will appear
in the target/scala-<version>/
directory. That jar file can be supplied
to spark-shell --jars <jarfile>
, given you have Spark installed on your
local machine. That same jar file could be supplied to spark-submit
if
you are running 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.