Skip to content

Latest commit

 

History

History
190 lines (127 loc) · 9.9 KB

configuration.md

File metadata and controls

190 lines (127 loc) · 9.9 KB
Raw

OnEarth Configuration

This documentation will go through the steps needed to configure the OnEarth server with imagery.

Apache and mod_onearth

Dependent RPMs:

  • onearth
  • onearth-mapserver

Steps:

Image Archive

Dependent RPMs:

  • gibs-gdal
  • onearth-mrfgen
  • onearth-vectorgen

Please refer to the following documentation: Creating Image Archive

Layer Reprojection

See the reprojection doc page.

Imagery Layers

Dependent RPMs:

  • gibs-gdal
  • onearth-config

Steps:

  • Update/Create OnEarth Support Configuration files
  • Generate MRF metadata file
  • Generate Color Map (Optional)
  • Generate Empty Tile (Optional)
  • Update/Create OnEarth Layer Configuration file
  • Generate Legend Images (Optional)
  • Execute OnEarth Layer Configuration tool
  • Restart Apache

The following steps involve the use of the OnEarth Layer Configuration tool. These steps should allow one to become familiar with the tool and demonstrate how to quickly configure a layer on the OnEarth server.

Update/Create OnEarth Support Configuration files

Ensure that the supporting configuration files for the OnEarth Layer Configuration tool have been properly configured for your environment. Please review Support Configuration Files before proceeding.

The default location for these configuration files is: /etc/onearth/config/conf

Schema files can be found here.

Generate MRF metadata file

The MRF metadata file refers to the .mrf portion of an MRF triplet of files. For example: MODIS_Aqua_AerosolTTTTTTT_.mrf

Configuration files for the server are generated by reading the MRF metadata files for each of the available layers. This allows the server to store a binary configuration that can be quickly accessed with minimal performance overhead.

The MRF metadata file may simply be copied from an existing image archive or generated from scratch using the mrfgen tool.

The following example shows how to generate an MRF file to be used as an archetype for the layer.

  1. Run the mrfgen tool to generate an MRF image. Source imagery may be found here. The test configuration may be found here.
mrfgen -c mrfgen_test_config.xml
  1. Copy the .mrf header file to a "headers" subdirectory with your layer configuration directory. The file can be renamed to something easier on the eyes. If there is a timestamp at the end of the filename, replace it with "TTTTTTT".
cp MYR4ODLOLLDY2014277_.mrf /etc/onearth/config/headers/MODIS_Aqua_AerosolTTTTTTT_.mrf

This can be used as the <HeaderFileName> in the layer configuration file (upcoming steps)

<HeaderFileName>MODIS_Aqua_AerosolTTTTTTT_.mrf</HeaderFileName>

Generate Color Map (Optional)

OnEarth supports the used of a color map within MRF imagery. Typically, the MRF will be generated using paletted PNG files as input, however, RGBA PNG files may be converted if a color map is provided. OnEarth uses the GIBS color map XML format (samples here). OnEarth also uses the color map for the generation of color legends (see the OnEarth Legend Generator for more details).

The OnEarth source currently does not include tools to generate a GIBS color map.

Generate Empty Tile (Optional)

An "empty tile" is a tile that is returned by the server when there are no data available. This may happen when a specified region contains no valid data, no data is available for a given time region (e.g., future date), or when there is an error with the server. In many cases, a client application prefers a tile being returned versus an error message due to ease of handling.

Two empty tiles are available in the source code. Typically a black opaque image is used for JPEG imagery, while a transparent image is used for PNG. There are reasons that these "empty tiles" may not be desired for use: the tiles may not be consistent with the colors in the actual imagery, or perhaps another color is preferred over black or transparent.

The oe_generate_empty_tile.py tool was designed to create a custom empty tile that is fitting for a given layer. The OnEarth Layer Configuration tool will automatically generate empty tiles by leveraging this tool if a colormap is specified (unless --skip_empty_tiles is used). But this can also be done manually by the following steps:

  1. Generate or choose a color map that matches the imagery. This sample can be used.

  2. Choose the desired color to be used as the nodata value for the empty tile. Simply set the nodata value to "true" for the chosen color.

<ColorMapEntry rgb="0,0,0" sourceValue="-9999" label="Missing Data -9999" transparent="true" nodata="true"/>
  1. Run the oe_generate_empty_tile.py tool passing in the color map, output format, tile size, and output file.
oe_generate_empty_tile.py -c MODIS_Terra_Chlorophyll_A.xml -f png -x 512 -y 512 -o empty_tile.png
  1. Use the output tile as the <EmptyTile> value in the layer configuration file in the next step
<EmptyTile>empty_tile.png</EmptyTile>

Note that mod_onearth uses a CGI script at each endpoint that will reference an empty tile should one not exist for the requested layer or if there is a problem retrieving it.

Update/Create OnEarth Layer Configuration file

A layer configuration file must be created to be used as input for the OnEarth Layer Configuration tool. An example is presented below. Please review this documentation for more detailed information: Layer Configuration File

<?xml version="1.0" encoding="UTF-8"?>
<LayerConfiguration>
	<Identifier>MODIS_Aqua_Aerosol</Identifier>
	<Title>MODIS Aqua Aerosol</Title>
	<FileNamePrefix>MODIS_Aqua_Aerosol</FileNamePrefix>
	<TiledGroupName>MODIS_Aqua_Aerosol tileset</TiledGroupName>
	<HeaderFileName>MODIS_Aqua_AerosolTTTTTTT_.mrf</HeaderFileName>
	<Compression>PNG</Compression>
	<TileMatrixSet>EPSG4326_2km</TileMatrixSet>
	<EmptyTile>empty_tile.png</EmptyTile>
	<Projection>EPSG:4326</Projection> 
	<EnvironmentConfig>../conf/environment_geographic.xml</EnvironmentConfig>
	<ArchiveLocation static="false" year="true" root="geographic">MODIS_Aqua_Aerosol</ArchiveLocation>
	<ColorMap>MODIS_Aqua_Aerosol-GIBS.xml</ColorMap>
	<Time>DETECT/P1D</Time>
</LayerConfiguration>

The file may need to be updated to fit your environment. Layer configuration files are generally kept in: /etc/onearth/config/layers

Note that the <ColorMap> element is referencing a sample file. A local color map file from the previous step may be used instead.

Generate Legend Images (Optional)

The OnEarth Layer Configuration tool can generate a color legend for each layer if a colormap is specified and the -g or --generate_legend option is used. The legends can also be created by running the oe_generate_legend.py tool.

There are many options for how to output the legend graphic. Please refer to the tool's documentation for specific details. The legends can be placed somewhere on the server that is accessible to web clients.

Execute OnEarth Layer Configuration tool

It is time to execute the OnEarth Layer Configuration tool after all of the configuration files have been properly created.

Run the oe_configure_layer with the layer configuration file

oe_configure_layer --conf_file layer_configuration_file.xml --generate_legend --restart_apache

The --generation_legend option is not needed if a legend is not desired or if it has already been created. The --restart_apache can also be skipped if a restart of Apache is not desired.

By default, the tool will generate the XML files for WMTS GetCapabilities, TWMS GetCapabilities, TWMS GetTileService, and the cache configuration files for both WMTS and TWMS. Each configured end point should include the appropriate files. There are some self-explanatory options for limiting which files are generated: -n, --no_twms -w, --no_wmts -x, --no_xml -z, --no_cache

The tool can also configure multiple layers by specifying a directory.

oe_configure_layer --layer_dir /etc/onearth/config/layers

If no configuration file or directory is specified, the tool will look for files files in a default directory relative to the layer configuration directory --lcdir.

There is a --generate_links option that will automatically create soft links to files designated as the "default" for time varying layers (read this documentation for more information on "Default Files").

Additionally, there is an option to generate mapfile configurations for MapServer: --create_mapfile. Mapfile header files must exist in the MapfileConfigLocation of the environment configuration. Resulting mapfiles will be placed in the location specified with MapfileLocation.

Restart Apache

Apache must be restarted for the configuration changes to take effect. Passing the -r or --restart_apache with oe_configure_layer will automatically restart the server, however, this can also be run manually:

sudo apachectl stop
sudo apachectl start

The imagery layers should now be available. If errors were discovered, please visit the troubleshooting documentation or contact us by sending an email to [email protected]

Log Metrics

Dependent RPMs:

  • onearth-metrics

Please refer to the following documentation: OnEarth Metrics