class ArcServer::REST::MapServer

Map services offer access to map and layer content. Map services can either be cached or dynamic. A map service that fulfills requests with pre-created tiles from a cache instead of dynamically rendering part of the map is called a cached map service. A dynamic map service requires the server to render the map each time a request comes in. Map services using a tile cache can significantly improve performance while delivering maps, while dynamic map services offer more flexibility. Map services should always be published as pooled services.

The REST API map service resource represents a map service. This resource works only with the default data frame of your published map document. This resource provides basic information about the map, including the layers that it contains, whether the map is cached or not, its spatial reference, initial and full extents, map units, and copyright text. It also provides some metadata associated with the service such as its service description, its author, and keywords. If the map is cached, then additional information about its tiling scheme such as the origin of the cached tiles, the levels of detail, and tile size is included. Note that multi-layer caches are only accessible in REST via export, and these requests are treated as a dynamic map service. Tile access is not supported in REST for multi-layer caches.

The map service resource supports several operations:

Attributes

url[R]

The REST url of a map service

Public Class Methods

new(url) click to toggle source

@param [String] url the REST url of a map service @example

ArcServer::MapServer.new("http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer")
# File lib/arcserver/rest/map_server.rb, line 57
def initialize(url)
  @url = url
end

Public Instance Methods

export(params = {}) click to toggle source

The export operation is performed on a map service resource. The result of this operation is a map image resource. This resource provides information about the exported map image such as its URL, its width and height, extent and scale.

Apart from the usual response formats of html and json, users can also request a format called image while performing this operation. When users perform an export with the format of image, the server responds by directly streaming the image bytes to the client. One must note that with this approach you don’t get any information associated with the exported map other than the actual image.

Note that the extent displayed in the exported map image may not exactly match the extent sent in the bbox parameter when the aspect ratio of the image size does not match the aspect ratio of the bbox. The aspect ratio is the height divided by the width. In these cases the extent is re-sized to prevent map images from appearing stretched. The exported map’s extent is sent along with the json and html responses and may be used in client side calculations. So it is important that the client-side code update its extent based on the response.

@param [Hash] params the query parameters to pass to the export operation

@option params [String, Symbol] :f (:image) The response format. The default response

format is html. If the format is image, the image bytes are directly streamed
to the client.

  # Values: html | json | image | kmz | pjson (pretty json)
  # Examples:
  :f => :json
  :f => 'kmz'

@option params [required, String, Array] :bbox The extent (bounding box) of

the exported image. Unless the bboxSR parameter has been specified, the
bbox is assumed to be in the spatial reference of the map.

  # Syntax: <xmin>, <ymin>, <xmax>, <ymax>
  # Examples:
  :bbox => "-104,35.6,-94.32,41"
  :bbox => [-104,35.6,-94.32,41]

  # Note: The bboxcoordinates should always use a period as the decimal separator
  # even in countries where traditionally a comma is used.

@option params [String, Array] :size ([400, 400]) The size (width * height) of the exported

image in pixels. If the size is not specified, an image with a default
size of 400 * 400 will be exported.

  # Syntax: <width>, <height>
  # Examples:
  :size => "600,550"
  :size => [600,550]

@option params [Integer] :dpi (96) The device resolution of the exported

image (dots per inch).

  # Example:
  :dpi => 300

@option params [Integer] :imageSR The well-known ID of the spatial reference

of the exported image. If the imageSR is not specified, the image will
be exported in the spatial reference of the map.

  # Example:
  :imageSR => 4326

@option params [Integer] :bboxSR The well-known ID of the spatial reference

of the bbox. If the bboxSR is not specified, the bbox is assumed to be
in the spatial reference of the map.

  # Example:
  :bboxSR => 4326

@option params [String, Symbol] :format (:png) The format of the exported

image.

  # Values: png | png8 | png24 | jpg | pdf | bmp | gif | svg | png32
  # Examples:
  :format => :png32
  :format => 'jpg'

  # Note: Support for the png32 format was added at 9.3.1. This format is only
  # available for map services whose supportedImageFormatTypes property includes PNG32

@option params [String] :layerDefs Allows you to filter the features of

individual layers in the exported map by specifying definition expressions
for those layers.

  # Syntax: layerId1:layerDef1;layerId2:layerDef2
  # (where layerId1, layerId2 are the layer ids returned by the map service resource)
  # Example:
  :layersDefs => "0:POP2000 > 1000000;5:AREA > 100000"
  :layersDefs => { 0 => "POP2000 > 1000000", 1 => "AREA > 100000" }

@option params [String, Hash<Symbol, Array>] layers Determines which layers appear on the exported

map. There are four ways to specify which layers are shown:

* show: Only the layers specified in this list will be exported.
* hide: All layers except those specified in this list will be exported.
* include: In addition to the layers exported by default, the layers specified in this list will be exported.
* exclude: The layers exported by default excluding those specified in this list will be exported.

    # Syntax: [show | hide | include | exclude]:layerId1,layerId2
    # where layerId1, layerId2are the layer ids returned by the map service resource      
    # Examples:
    :layers => "show:2,4,7"
    :layers => { :show => [2,4,7] }

@option params [true, false] transparent (false) If true, the image will be exported

with the background color of the map set as its transparent color. The default
is false. Only the png and gif formats support transparency.  Internet
Explorer 6 does not display transparency correctly for png24 image formats.

@example

# create a map service
map_service = MapServer.new("http://sampleserver1.arcgisonline.com/ArcGIS/rest/services/Specialty/ESRI_StateCityHighway_USA/MapServer")

# Export a map
map_service.export(:bbox => "-127.8,15.4,-63.5,60.5")

# Export a map and change imageSR to 102004 (USA_Contiguous_Lambert_Conformal_Conic projection)
map_service.export(:bbox => "-127.8,15.4,-63.5,60.5", :imageSR => 102004, :f => "html")

# Export a map, change imageSR to 102004 (USA_Contiguous_Lambert_Conformal_Conic projection),
# set image size to a width and height of 800x600, format to gif, and transparent to true.
map_service.export(:bbox => "-115.8,30.4,-85.5,50.5", :size => "800,600", :imageSR => 102004, :format => "gif", :transparent => false, :f => "html")

# Export the same map as above but change the output format to pretty json (f=pjson).
map_service.export(:bbox => "-115.8,30.4,-85.5,50.5", :size => "800,600", :imageSR => 102004, :format => "gif", :transparent => false, :f => "pjson")

@example

JSON Response Syntax:
{
  "href" : "<href>",
  "width" : <width>,
  "height" : <height>,
  "extent" : {<envelope>},
  "scale" : <scale>
}

JSON Response Example:
{
  "href" : "http://atlantic/arcgisoutput/_ags_map42ef5eae899942a9b564138e184a55c9.png",
  "width" : 400,
  "height" : 400,
  "extent" : {
    "xmin" : -109.55,
    "ymin" : 25.76,
    "xmax" : -86.39,
    "ymax" : 49.94,
    "spatialReference" : { "wkid" : 4326 }
  },
  "scale" : 2.53E7
}

@return [HTTParty::Response] the HTTP response

# File lib/arcserver/rest/map_server.rb, line 217
def export(params = {})
  params = {
    :bbox        => params[:bbox],
    :f           => params[:f]           || :image,
    :format      => params[:format]      || :png24,
    :transparent => params[:transparent] || true,
    :size        => params[:size],
    :dpi         => params[:dpi]
  }
  HTTParty.get("#{url}/export", :query => params)
end