Configure the Tile Server

Once you have copied an existing Aperture Tiles application as a template, you should customize the Tile Server, which passes your tile data to the Client.

The Tile Server in your new template relies on the following configuration files:

  • Web XML, which defines which modules Guice will use.
  • Tile Properties, which specifies constants used by Guice during initialization, including the location of your Spark installation, and the location of some server configuration files.
  • Layers, which defines the individual layers of data that can be overlaid on your base map. The layers file also indicates whether rendering should be performed by the server or the client.

The remainder of the configuration, which includes instantiation of the map, its base features and axis configuration, should be handled in the Application JavaScript (/src/main/webapp/js/app.js).


Edit the client web.xml file in new-project/src/main/webapp/WEB-INF/:

  1. If you performed a custom tile generation, edit the guice-modules parameter to pass in any custom modules you created (e.g., your custom Tile Serialization Factory).
  2. If required, uncomment the relevant Spark lines in the guice-modules to enable live tiling or drill-through to raw data.

Tile Properties

Edit the client file in new-project/src/main/resources/. This file specifies parameters for use by Guice, such as the location of your layer and annotation directories. Additional Spark parameters are available for on-demand tile generation and data drill down:

  • The location of your Spark master
  • The name under which the Aperture Tiles web service should appear in the Spark web interface.
  • The home directory of Spark
  • Any JARs you want to add to the Spark context


The layers file describes the tile layers to be made available to the server and client application. Parameters in the layers file are split into two sections: those in the public node are accessible from the client, while those under the private note are not.

Layer file examples can be found in in the Julia example at tile-examples\julia-demo\src\main\resources\layers and the Twitter Topics example at tile-examples\twitter-topics\twitter-topics-client\src\main\resources\layers.


The ID parameter uniquely identifies the layer.

Property Description
id Layer identification string, which is used in all layer-related REST calls. Must conform to JSON property name format.

Public Parameters

Parameters in the public node section of the layers.json file are accessible from the client.


The pyramid parameters describe the extent of the data in the layer. The values that you provide in this section must match the values in your data source and in your map configuration.

For cross-plot maps, the type should always be set to AreaOfInterest. Also include the minimum and maximum values on the X and Y axes in your cross-plot.

pyramid: {
    type: "AreaOfInterest",
    minX : 1,
    maxX : 6336769,
    minY : 0,
    maxY : 500000

For geographic maps, the type should always be set to WebMercator. No minimum and maximum X and Y values are required for this layer type.

pyramid: {
    type: "WebMercator"

NOTE: Your layer and map pyramid configurations much match each other.


The renderer defines how tiles are rendered on the server side. Renderers are dependent on the type of tile data. The renderer options are:

Property Description
  • 'heatmap': Renders to a heatmap, based on a standard Avro double-valued tile
  • 'doubleseries': Renders to a series of heatmaps, based on a standard Avro double-series-valued tile
  • 'doublestatistics': Renders tile's total hit and % coverage as text to the tile
  • 'textscore': Renders to an image showing scored words, with bars based on their score
ramp Determines the color scale applied to the data points based on their concentration. The default color scales are:
  • 'hot': Warm orange ramp.
  • 'neutral': Black-grey-white ramp.
  • 'cool': Cool blue ramp.
  • 'spectral': Red-green-yellow ramp.
  • 'flat': Single color (white) ramp.
rangeMin Minimum percentage to clamp the low end of the color ramp.
rangeMax Maximum percentage to clamp the low end of the color ramp.
opacity Opacity of the rendered tile layer expressed as a decimal ranging from 0 (completely transparent) to 1 (completely opaque).
enabled Indicates whether the layer is enabled on load.

Value Transformer

The valueTransform defines the type of transformation that can be applied to the data values when determining color:

Value Description
minmax Do not change the value, but allow capping within min and max values.
sigmoid Apply a sigmoid function to each value to make them fall between fixed values. With data that can be infinitely large in either direction, this can be used to bring it into finite, displayable bounds.

Uses the following properties to indicate the minimum and maximum expected values while allowing values infinitely above or below them.

  • layerMin
  • layerMax
These two values should be symmetric around the desired central value.
half-sigmoid Apply a sigmoid function to each value to make them fall between fixed values. With data that can be infinitely large in one direction only, this can be used to bring it into finite, displayable bounds.

Uses the following properties:

  • layerMin corresponds to the minimum allowed data value
  • layerMax indicates the maximum expected data value while allowing values infinitely above it
log10 Take the log (base 10) of each value. Useful when displaying data that can be large (but not infinite) in one direction only. Uses the layerMax property to indicate the maximum.

Private Parameters

Parameters in the private node section of the layers.json file are not accessible from the client.


The data parameters specify the location of the tiles that you created. If you are using HBase, separate parameters are required.

Must match the name of the folder to which the tiles were saved during the generation process, which is composed of the following parameters from the Tiling Property File:


Where oculus.binning.yField is set to 0 if no yField name is specified.
Indicates the file format of your tiles:
Tiles are stored in HBase
Tiles are stored in an uncompressed directory in a local filesystem
Tiles are stored in compressed file in a local filesystem
Root path in which the tiles are stored. Not used for HBase.
Name of the compressed file in which tiles are stored. Only used for ZIP files.
Zookeeper quorum location needed to connect to HBase.
Port through which to connect to zookeeper. Typically defaults to 2181.
Location of the HBase master on which the tiles are saved.

Next Steps

For details on configuring a Tile Client to display your tile-based visual analytic, see the Configure the Tile Client topic.