Stretch renderer

View on GitHub
Sample viewer app

Use a stretch renderer to enhance the visual contrast of raster data for analysis.

Image of stretch renderer

Use case

An appropriate stretch renderer can enhance the contrast of raster imagery, allowing the user to control how their data is displayed for efficient imagery analysis.

How to use the sample

Choose one of the stretch parameter types from the wrench icon in the action bar:

  • Standard deviation - a linear stretch defined by the standard deviation of the pixel values
  • Min-max - a linear stretch based on minimum and maximum pixel values
  • Percent clip - a linear stretch between the defined percent clip minimum and percent clip maximum pixel values

Then configure the parameters and tap 'Render'.

How it works

  1. Create a Raster from a raster file.
  2. Create a RasterLayer from the raster.
  3. Create a Basemap from the raster layer with Basemap(RasterLayer) and set it to the map with ArcGISMap(basemap).
  4. Create a StretchRenderer, specifying the stretch parameters and other properties.
  5. Set the stretch renderer on the raster layer with rasterLayer.setRasterRenderer(stretchRenderer).

Relevant API

  • MinMaxStretchParameters
  • PercentClipStretchParameters
  • Raster
  • RasterLayer
  • StandardDeviationStretchParameters
  • StretchParameters
  • StretchRenderer

Offline Data

  1. Download the data from ArcGIS Online.
  2. Extract the contents of the downloaded zip file to disk.
  3. Open your command prompt and navigate to the folder where you extracted the contents of the data from step 1.
  4. Push the data into the scoped storage of the sample app: adb push raster-file /Android/data/com.esri.arcgisruntime.sample.stretchrenderer/files/raster-file

About the data

This sample uses a raster imagery tile of an area of forested mountainous terrain and rivers.

Additional information

See Stretch function in the ArcMap documentation for more information about the types of stretches that can be performed.

Tags

analysis, deviation, histogram, imagery, interpretation, min-max, percent clip, pixel, raster, stretch, symbology, visualization

Sample Code

MainActivity.javaParametersDialogFragment.java
                                                                                                                                                                        
/* Copyright 2017 Esri
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */

package com.esri.arcgisruntime.sample.stretchrenderer;

import java.util.Collections;

import android.os.Bundle;
import android.view.Menu;
import android.view.MenuInflater;
import android.view.MenuItem;

import androidx.appcompat.app.AppCompatActivity;
import androidx.fragment.app.FragmentManager;
import com.esri.arcgisruntime.layers.RasterLayer;
import com.esri.arcgisruntime.mapping.ArcGISMap;
import com.esri.arcgisruntime.mapping.Basemap;
import com.esri.arcgisruntime.mapping.view.MapView;
import com.esri.arcgisruntime.raster.MinMaxStretchParameters;
import com.esri.arcgisruntime.raster.PercentClipStretchParameters;
import com.esri.arcgisruntime.raster.Raster;
import com.esri.arcgisruntime.raster.StandardDeviationStretchParameters;
import com.esri.arcgisruntime.raster.StretchParameters;
import com.esri.arcgisruntime.raster.StretchRenderer;

public class MainActivity extends AppCompatActivity implements ParametersDialogFragment.ParametersListener {

  private FragmentManager mFragmentManager;

  private MapView mMapView;
  private RasterLayer mRasterLayer;

  private int mMin;
  private int mMax;
  private int mPercentClipMin;
  private int mPercentClipMax;
  private int mStdDevFactor;
  private StretchType mStretchType;

  @Override
  public void returnParameters(int min, int max, int percentClipMin, int percentClipMax, int stdDevFactor,
      StretchType stretchType) {
    //gets dialog box parameters and calls updateRenderer
    mMin = min;
    mMax = max;
    mPercentClipMin = percentClipMin;
    mPercentClipMax = percentClipMax;
    mStdDevFactor = stdDevFactor;
    mStretchType = stretchType;
    updateRenderer();
  }

  @Override
  protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    //set default values for stretch parameters
    mMin = 0;
    mMax = 255;
    mPercentClipMin = 0;
    mPercentClipMax = 99;
    mStdDevFactor = 1;
    mStretchType = StretchType.MIN_MAX;
    // retrieve the MapView from layout
    mMapView = findViewById(R.id.mapView);
    mFragmentManager = getSupportFragmentManager();

    // create raster
    Raster raster = new Raster(getExternalFilesDir(null) + getString(R.string.stretch_renderer_shasta_tif));
    mRasterLayer = new RasterLayer(raster);
    // create a basemap from the raster layer
    Basemap basemap = new Basemap(mRasterLayer);
    ArcGISMap map = new ArcGISMap(basemap);
    // add the map to a map view
    mMapView.setMap(map);
    updateRenderer();
  }

  /**
   * Creates StretchRenderer of the chosen type: MinMax, PercentClip or StandardDeviation.
   */
  private void updateRenderer() {
    StretchParameters stretchParameters;
    switch (mStretchType) {
      default:
        stretchParameters = new MinMaxStretchParameters(Collections.singletonList((double) mMin),
            Collections.singletonList((double) mMax));
        break;
      case PERCENT_CLIP:
        stretchParameters = new PercentClipStretchParameters(mPercentClipMin, mPercentClipMax);
        break;
      case STANDARD_DEVIATION:
        stretchParameters = new StandardDeviationStretchParameters(mStdDevFactor);
    }
    StretchRenderer stretchRenderer = new StretchRenderer(stretchParameters, null, true, null);
    mRasterLayer.setRasterRenderer(stretchRenderer);
  }

  @Override
  public boolean onCreateOptionsMenu(Menu menu) {
    MenuInflater inflater = getMenuInflater();
    inflater.inflate(R.menu.blend_parameters, menu);
    return super.onCreateOptionsMenu(menu);
  }

  @Override
  public boolean onOptionsItemSelected(MenuItem item) {
    //send parameters to fragment
    ParametersDialogFragment paramDialog = new ParametersDialogFragment();
    Bundle stretchParameters = new Bundle();
    stretchParameters.putInt("min", mMin);
    stretchParameters.putInt("max", mMax);
    stretchParameters.putInt("percent_clip_min", mPercentClipMin);
    stretchParameters.putInt("percent_clip_max", mPercentClipMax);
    stretchParameters.putInt("std_dev_factor", mStdDevFactor);
    stretchParameters.putSerializable("stretch_type", mStretchType);
    paramDialog.setArguments(stretchParameters);
    paramDialog.show(mFragmentManager, "param_dialog");
    return super.onOptionsItemSelected(item);
  }

  @Override
  protected void onPause() {
    super.onPause();
    mMapView.pause();
  }

  @Override
  protected void onResume() {
    super.onResume();
    mMapView.resume();
  }

  @Override
  protected void onDestroy() {
    super.onDestroy();
    mMapView.dispose();
  }

  enum StretchType {
    MIN_MAX("Min Max"),
    PERCENT_CLIP("Percent Clip"),
    STANDARD_DEVIATION("Standard Deviation");

    private final String stringValue;

    StretchType(String toString) {
      stringValue = toString;
    }

    @Override public String toString() {
      return stringValue;
    }
  }
}