Customize the map

This topic explains ways to customize your map (JMap instance), for example, by controlling the animation, enabling layers to wrap around the date line, or adding a grid.

Enable wrap around

The world is round; however, most flat representations of the Earth only extend up to 180 degrees East and West longitude. This makes it difficult to visualize areas that span across the date line, or routes that traverse the Pacific Ocean. By enabling wrap around on a map, the eastern and western hemispheres wrap around each other forming a continuous map and giving the impression that the map is endless. Panning a map becomes similar to spinning a globe.

By default, the map layers added to a map (JMap instance) do not wrap around the date line. If you want the map's layers to wrap around the date line, set this on the map as follows:



The following requirements must be satisfied before enabling wrap around on a map:

  • The map's full extent must cover the world.
  • The map's spatial reference must be WGS 84 (WKID=4326) or Web Mercator (WKID=102113, 102100, or 3857). This means that all tiled layers in the map must belong to one of these spatial references. Dynamic layers, on the other hand, can be in any spatial reference because they are capable of reprojecting their data.
  • Dynamic layers must be based on map services from ArcGIS Server 10.0 or higher. This is because earlier versions of the REST API do not support well-known text (WKT) values for spatial reference, which is required for making dynamic map services support wrap around.

Display 'no data' tiles

Tile caches for cached map services usually do not have a tile for every single level of detail, everywhere in the extent of the area of coverage of the service. In a Java map application, the map control allows you to zoom or pan to one of these levels of details for which no tile exists. In your application, you can choose to show a standard 'no data' tile when this occurs, or you can show a resampled tile from the nearest level of detail for this area. The default behavior is to show a resampled tile, such that if you are zooming into an area and you get to the point where no tiles are available, you start to see the same tile you were seeing at the previous zoom level, but larger. The code snippet below shows how to set the map to show or hide the 'no data' tiles:

// show 'no data' tiles
// hide 'no data' tiles

Below is an example of what a 'no data' tile looks like:

'no data' tile

Control the animation

Methods on the JMap component allow you to control the animation mode and duration (animation is turned on by default). The code snippet below shows how to set the animation duration to 1 second, or turn the animation off:

// set a custom animation duration (1 second) on panning and zooming
// turn the animation off

Display a grid

You can add a grid to a map by calling the getGrid() method on the JMap instance and choosing the grid type you want to display. By default, the grid type is None meaning no grid displays. As an example, the code snippet below allows you to show a grid of type MGRS (Military Grid Reference System) in your map:

// adds an MGRS grid to the JMap instance

The result is an MGRS grid displaying in your map, as in the following screen capture:

MGRS grid added to a map

Methods on the Grid class allow you toggle the visibility of the grid and change the grid type to display on-the-fly. For example, by changing the grid type in the preceding code sample from MGRS to LAT_LON, you would instead get a latitude-longitude grid displaying on your map. In addition, you can further customize the grid by controlling the following:

  • Grid label visibility
  • Grid label color
  • Grid line color
  • Grid line width

Customizing these aspects of the grid may be desirable depending on, for example, which basemap you are using and which part of the world your application focuses on. The code snippet below sets a custom line color, label color, and line width on a grid:

// set up some custom grid colors and line widths 
int gridLevels = map.getGrid().getLevelCount();
for (int level = 0; level < gridLevels; level++) {
  map.getGrid().setLineColor(level, Color.RED);
  map.getGrid().setLabelColor(level, Color.CYAN);
  map.getGrid().setLineWidth(level, 1);

Toggle the Esri logo

The Esri logo displays in a map by default but you can control whether this logo shows or not. The code snippet below toggles off the Esri logo:

// toggle off the Esri logo

Customize layer display

Methods in the API give you the ability to adjust the brightness, contrast, and gamma levels of tiled and dynamic layers. Changes in brightness, contrast, and gamma levels are achieved by modifying the RGB values of image pixels in the layer to which the function applies. Brightness, contrast, and gamma correction can be combined and are applied in this order. In the API, the range of values for these three layer display properties is –100 to 100, with a default value of 0. Any value outside this range will be clamped to the minimum (–100) or maximum (100) allowed value.

The following code snippet shows how to adjust the brightness, contrast, and gamma properties of a tiled layer:


Brightness, contrast, and gamma correction are best represented as a color curve function that transforms an input color in the domain of [0-255] (x-axis) to the range of [0-255] (y-axis). The most trivial function is y=x, which is equivalent to brightness, contrast, and gamma at values of 0:

layer y=x


Brightness increases (or decreases) the pixel value while preserving the maximum (or minimum) pixel value. For example, when increasing brightness, the darker a source pixel is, the more its brightness increases. A +100 setting raises black (0) to medium gray (128).

layer increases brightness


Setting a higher contrast value increases the difference between the pixel color and medium gray; therefore, making bright colors brighter and dark colors darker. The following shows how a tiled layer changes from the default of 0 for contrast to a +50 setting.

tiled layer changes


Increasing the gamma value essentially increases the contrast between colors in an image, but preserves the extremes, and focuses instead on highlights and shadows that the human eye typically has trouble differentiating between (it is a non-linear function). The following is an example of a tiled layer with the default gamma value on the left and a gamma value of –50 on the right:

tiled layer with gamma values

Trial and error may be best when it comes to setting the combination of values to have the desired effect on the layer of your choice.