https://github.com/geotrellis/geotrellis-server
Tools for building raster processing and display services
https://github.com/geotrellis/geotrellis-server
geotrellis geotrellis-server maml map-algebra ogc tms wcs wms wmts
Last synced: 8 months ago
JSON representation
Tools for building raster processing and display services
- Host: GitHub
- URL: https://github.com/geotrellis/geotrellis-server
- Owner: geotrellis
- License: apache-2.0
- Created: 2017-11-22T16:47:51.000Z (over 8 years ago)
- Default Branch: main
- Last Pushed: 2024-05-14T12:39:46.000Z (about 2 years ago)
- Last Synced: 2025-05-14T11:51:01.757Z (about 1 year ago)
- Topics: geotrellis, geotrellis-server, maml, map-algebra, ogc, tms, wcs, wms, wmts
- Language: Scala
- Homepage:
- Size: 2.52 MB
- Stars: 74
- Watchers: 9
- Forks: 24
- Open Issues: 28
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- Awesome-Geospatial - GeoTrellis Server - Tools for building raster processing and display services. It supports WMS, WCS, WMTS and can use individual rasters, STAC Catalogs (through the STAC API service) and GeoTrellis Layers as input raster sources. (Web Map Server)
README
# GeoTrellis Server
[](https://github.com/geotrellis/geotrellis-server/actions/workflows/ci.yml) [](http://search.maven.org/#search%7Cga%7C1%7com.azavea.geotrellis) [](https://oss.sonatype.org/content/repositories/snapshots/com/azavea/geotrellis/geotrellis-server-core_2.12/)
GeoTrellis Server is a set of components designed to simplify
viewing, processing, and serving raster data from arbitrary sources
with an emphasis on doing so in a functional style. It aims to ease
the pains related to constructing complex raster processing workflows
which result in TMS-based (z, x, y) and extent-based products.
In addition to providing a story about how sources of imagery can be displayed
or returned, this project aims to simplify the creation of dynamic,
responsive layers whose transformations can be described in MAML
([Map Algebra Modeling Language](https://github.com/geotrellis/maml/)).
### Getting Started with GeoTrellis Server
GeoTrellis Server is currently available for Scala 2.13 and 2.12.
To get started with SBT, simply add the following to your build.sbt file:
```scala
libraryDependencies += "com.azavea.geotrellis" %% "geotrellis-server-core" % ""
```
### High level concepts
Imagine you've got a simple case class which is sufficient to identify
layers of imagery for an application you're working on.
```scala
import java.net.URI
case class ImageryLayer(location: URI)
```
Imagine further that you'd like to enable your application to compose these
layers together via map algebra to produce derived layers and that the
combinations can't be known at compile-time (users will be deciding
which - if any - map algebra to run). This is a job that GeoTrellis
server can radically simplify. Because we're dealing with behavior
specified at runtime, we need to evaluate program descriptions rather
than simple, first-order parameters - the task for which
[MAML](https://github.com/geotrellis/maml/) was written.
```scala
// This node describes a `LocalAdd` on the values eventually
// bound to `RasterVar("test1")` and `RasterVar("test2")
val simpleAdd = Addition(List(RasterVar("test1"), RasterVar("test2")))
// This describes incrementing every value in the eventually bound raster by 1
val plusOne = Addition(List(RasterVar("additionRaster1"), IntLit(1)))
```
Because MAML encodes map alagebra transformations in data, actually
executing a MAML program for practical purposes can be difficult and
unintuitive. GeoTrellis server bridges this gap by providing a
typeclass-based means of extending source types in client applications
with the behaviors necessary to actually evaluate a MAML AST.
The following example demonstrates what is required to generate
functions which produce extents provided MAML program descriptions. For
a more complete example, check out
[CogNode](example/src/main/scala/geotrellis/server/example/cog/CogNode.scala).
```scala
import io.circe._
import io.circe.syntax._
import io.circe.generic.semiauto._
import cats._
import cats.effect._
import com.azavea.maml.ast._
import com.azavea.maml.eval.BufferingInterpreter
import geotrellis.server._
// This class points to a COG and specifies a band of interest
case class RasterRef(uri: URI, band: Int)
// We need to provide some implicit evidence. Most applications can do this within companion objects
object RasterRef {
// reification means 'thingification', and that's what we're proving we can do here
implicit val rasterRefExtentReification: ExtentReification[RasterRef] = new ExtentReification[RasterRef] {
def extentReification(self: CogNode, buffer: Int)(implicit contextShift: ContextShift[IO]): (Extent, CellSize) => IO[Literal] = ???
}
// We can lean on circe's automatic derivation to provide an encoder
implicit val rasterRefEncoding: Encoder[RasterRef] = deriveEncoder[RasterRef]
}
// A source from which MAML evaluation will be able to derive necessary artifacts
val reference = RasterRef("http://some.url.com", 1)
// We need to key provided references based on the ID of the Var they'll replace
val parameters = Map("additionRaster1" -> reference)
// This is an interpeter GT Server will use to roll up the tree + params to some result
val interpreter = BufferingInterpreter.DEFAULT
// Not yet a result: we can use the result here to produce artifacts for different extent inputs
val tileEval = LayerExtent.apply(IO.pure(plusOne), IO.pure(parameters), interpreter)
val targetExtent: Extent = ??? // Where should the tile come from?
val targetCellSize: CellSize = ??? // What resolution should the tile be?
// Branch on Valid/Invalid and print some info about which branch we're on
tileEval(targetExtent, targetCellSize) map {
case Valid(tile) =>
println("we did it, a tile: (rows: ${tile.rows}, cols: ${tile.cols})")
case Invalid(err) =>
println("Ran into an error (${err.asJson}) during MAML evaluation of AST (${plusOne.asJson}) with params (${params.asJson})")
}
```
`LayerExtent` is joined by two other objects which organize evaluation
strategies for different products:
- `LayerExtent`: Constructs functions that produce a `cats.data.Validated` instance
containing a `Tile` (given an extent) or else `MamlError`s. Requires
`ExtentReification` and `Encoder` evidence
- `LayerTms`: Constructs functions that produce a `cats.data.Validated` instance
containing a `Tile` (given the tms Z, X, Y coordinates) or else
`MamlError`s. Requires `TmsReification` and `Encoder` evidence
- `LayerHistogram`: Constructs functions that produce a `cats.data.Validated` instance
containing a `Histogram` or else `MamlError`s. Requires
`ExtentReification`, `Encoder`, and `HasRasterExtents` evidence
Each of these objects is a response to distinct needs encountered when
writing raster-based applications. Included in each object are methods
which encode several strategies for evaluating their products. The strategies
currently available are:
- `apply`: Takes parameters, a MAML AST, and a MAML `Interpreter` and evaluates accordingly
- `generateExpression`: parameters, a function which will generate an AST based on the
parameters, and a MAML `Interpreter`
- `curried`: Takes an AST and a MAML `Interpreter` (this method produces an
intermediate, curried, function which expects a parameter map to
evaluate)
- `identity`: Evaluates a proven source without any MAML evaluation (useful for
quickly defining a static layer viewer or debugging implicit evidence behavior
### Running an example
Three example servers are available which can be run through the provided
makefile. These examples have been implemented via [http4s](https://http4s.org/),
which has a pleasant, clean API and plays nicely with the
[cats](https://typelevel.org/cats/) and [cats-effect](https://typelevel.org/cats-effect/)
libraries.
1. A server and simple UI that evaluates weighted overlays between
arbitrary COGs. This demo includes a simple UI, available at http://localhost:9000/ for a
```bash
./scripts/server --overlay
```
2. Integrates GTServer components with application-specific persistence needs.
```bash
./scripts/server --persistence
```
3. Illustrates GTServer evaluating a remote-sensing classic, the NDVI.
```bash
./scripts/server --ndvi
```