Make a list of missing DOC pages

[pomadchin]

Apart of updateing our docs in general, it makes sense to add some extra doc pages basing on the gitter channel demands. The output of this task would be a list of pages we definitely need to cover since there is a high demand in them.

[echeipesh]

Potentially we can adopt "answer to the documentation" approach to common questions if we have some docs/FAQ to point to. This can be more sustainable because it would allow us to make a small change to the docs every time a new questions comes up and subsequently just point to the updated section.

This issue is to make a list of currently commonly asked questions and topics such that we can scope and plan it in larger GT docs over-hall. This does not need to be exhaustive, just a first honest pass at such list.

[pomadchin]

WARNING: this is only a first pass of creating a list of topics, it should be cleaned up

A couple of things we may want to reflect in docs / project examples to support GeoTrellis. Some of these questions can be addressed in the FAQ, some in the example projects and referenced from FAQ.

For some of the points below it would be enough just to fix the doc page. For some of them to add a proper reference into docs.

• Docs are in general not up to date, they are till only for GT 2.0

• What does 'install geotrellis mean'? (see two example projects)

  • "How to get started"?

• Quick start project (without spark)

  • How to set the Geotrellis non sparky project?
  • How to set the SBT project
  • How to build assembly (taking into account SPI and reference.conf)
  • the usual error is smth like: - Key not found: 'keyname'.
  • RasterSources are not resolved
  • SBT, MVN and GRADLE examples?

• Quick start Spark project reference (we already have it, more references and an updated repo was required)

• Examples

  • Mapalgebra examples, LandsatTutorial: https://github.com/geotrellis/geotrellis-landsat-tutorial
  • QA band masking example
  • Planet examples
  • How to do TOA correction?
  • Polygonal Summaries example: we probably need smth like Chatta demo
  • We have some missing API (that was present in eraly versions): https://github.com/locationtech/geotrellis/issues/3157
  • GeoTrellis + server examples and how to build assembly
  • GeoTrellis server
  • OGC Standards support

• RasterSources API

  • What is the relation to the old API
  • Examples with S3, HDFS, LocalFS, Azure and GC
  • With credentials configuration
  • What dependencies to add
  • How GDAL / PDAL picks up credentials?
  • Read full tile, by window, by extent
  • Reproject, resampling
  • what is resampleMethod?
  • MosaicRasterSource
  • LayoutTileSource
  • Examples with multiple files
  • RasterSourceSummary
  • Explanations of the URI schema
  • OverviewStrategy

• GDAL examples through RasterSources API with limitations deiscription

  • Should contain GDAL WARP references and its limitations
  • Windows limited support
  • How to configure GDAL through application.conf

• Rasters:

  • CellType and NoData
  • How to merge rasters and why cellType / nodata matters
  • How to get rid of black landsat borders / nodata black areas
  • How to render png / jpg / grayscale
  • How to persist TIFF, add ColorInterp, TIFFTags
  • Supported cellTypes
  • CellType conversions and relations between them
  • What are overviews
  • Vectorize
  • Rendering ColorMaps and Ramps
  • IntHisotgram and Streaming hisotgram - why they are different
  • File formats support:
  • NetCDF (through GDAL)
  • TIFF (JVM and GDAL)
  • JP2 (GDAL)
  • Everything GDAL supports
  • Convert from Geogrpahical coords <-> GRID coords
  • mapToGrid and gridToMap functions explanation
  • what is MapTransform
  • Color correction examples
  • clamp
  • rescale
  • normalize
  • What is a CellSize, whare are the CellSize units
  • Relation between Tile and MultibandTile
  • What is Raster
  • What are GeoTiff types
  • Subbands selection

• Vectors

  • How to use new JTS API
  • Convert Geometries to and from JSON
  • We dont depend on Spary anymore
  • Convert to and from WKB / WKT
  • Rasterization

• Proj4

  • Parse CRS from proj4 / wkt / epsg code

• Vectortile

  • How to read in mbtiles
  • How to process / work with this subproject; we need some example with filtering out geometries of mapbox QA tiles basing on mapbox countries JSON?

• GeoTrellis Layers

  • How to read by Query
  • Spatial queries
  • Temporal queries
  • How to read by K,V
  • overzoom support (mention how it works)
  • What SpatialKey means
  • What is layout?
  • What is a SpaceTimeKey
  • ZCurve defintion and usage
  • What is TileLayerMetadata
  • What is pyramid and relation to ZoomedLayoutScheme
  • How to build Pyramid?
  • How to read / write custom attributes in the AttributeStore
  • Focal, Local, Zonal operations
  • Hisrograms
  • Hillshade
  • Slope

COGLayers:

• Some users are aware of COGs disadvantage (they are still separate files => lots of requests are required to read in a layer)
• Describe them like GeoTrellis Layers and what is the relation to them
  • (Mb it makes sense to mention it only after the STAC refactor)

• Spark use case

  • What is the relation to the old API
  • Ingest examples without ETL package
  • geotrellis-etl is not supported
  • Through the pipeline project (if the user thinks that it is really n3eccesary to have smth like ETL + it has a convinient JSON DSL)
  • Without Pipeline project (RasterSourceRDD)
  • Temporal ingest / queries
  • GDALRasterSources usage
  • There is a need to install GDAL on a cluster
  • Focal and Zonal operations
  • What is .stich() method and why it is exapensive
  • Why it usually very expenssive to read a single tiff, chunk it, and sitch back
  • Yarn usage
  • K8S usage

• Relation to RasterFrames

• GeoTrellis PointCloud references (in the beginning of this year there was an intrest in its usage)

  • How to get started, to use, some primitive RasterSources examples
  • Spark example
  • What is PDAL
  • Credentials
  • Entwine
  • Pipeline
  • Known limitations on Spark and the reason of OOMs happening, what is Kryo registartor
  • Triangulation support

• geotrellis-slick is not supported

• Relation to GeoPySpark and what to use instead

  • it is still a pretty popular topic ~ "how to use geopyspark"

• What versions of Spark, Cassandra, Accumulo, HBase, S3 SDK we use and support

• MAML Description (there were no explicit questions, but questions about ETL and JSON descriptions of what should happen to rasters can be interesting to users)

  • Lazy rasters and lazy operations on them

[jpolchlo]

My comments on this great list:

1. I think there's no reason to even mention the defunct GeoPySpark project. We're moving towards RasterFrames; that should be where we focus our efforts (and it has a python interface).

2. Pointcloud doc suggestions should move to an issue in that project. We can link to it from GT docs.

3. If we're linking to supplemental projects, then let's not forget VectorPipe (related to both vectortiles and rasterframes).

[pomadchin]

Just a clarification: this list covers the entire geotrellis ecosystem and is based on often gitter questions only. Semanitcs of some points from the list is preserved.

[CloudNiner]

Going to close as this list significantly informed #3304 and the list of items to ensure we capture in that effort.