# Background methods

I’ve called background methods those functions useful for drawing borders, lands, etc. to distinguish them from those aimed to draw user data.

## arcgisimage

Downloads and plots an image using the arcgis REST API service

arcgisimage(server=”http://server.arcgisonline.com/ArcGIS”, service=”ESRI_Imagery_World_2D”, xpixels=400, ypixels=None, dpi=96, verbose=False, **kwargs)

- server can be used to connect to another server using the same REST API

- service is the layer to draw. To get the full list of available layers, check the API web page,

- xpixels actually sets the zoom of the image. A bigger number will ask a bigger image, so the image will have more detail. So when the zoom is bigger, the xsize must be bigger to maintain the resolution

- ypixels can be used to force the image to have a different number of pixels in the y direction that the ones defined with the aspect ratio. By default, the aspect ratio is maintained, which seems a good value

- dpi is the image resolution at the output device. Changing its value will change the number of pixels, but not the zoom level

- verbose prints the url used to get the remote image. It’s interesting for debugging

An important point when using this method is that the projection must be set using the epsg argument, unless 4326, or cyl in Basemap notation is used. To see how to set a projection this way, see the section Using epsg to set the projection

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt

    map = Basemap(llcrnrlon=3.75,llcrnrlat=39.75,urcrnrlon=4.35,urcrnrlat=40.15, epsg=5520)
    #http://server.arcgisonline.com/arcgis/rest/services

    map.arcgisimage(service='ESRI_Imagery_World_2D', xpixels = 1500, verbose= True)
    plt.show()

The example shows Menorca island using the UTM projection at the zone 31N, and can be used with many layers:

The default ESRI_Imagery_World_2D layer

The World_Shaded_Relief layer

## bluemarble

Plots the bluemarble image on the map.

bluemarble(ax=None, scale=None, **kwargs)

- The scale is useful to downgrade the original image resolution to speed up the process. A value of 0.5 will divide the size of the image by 4

- The image is warped to the final projection, so all projections work properly with this method

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt

    map = Basemap(llcrnrlon=-10.5,llcrnrlat=33,urcrnrlon=10.,urcrnrlat=46.,
                 resolution='i', projection='cass', lat_0 = 39.5, lon_0 = 0.)

    map.bluemarble()

    map.drawcoastlines()

    plt.show()

## drawcoastlines

Draws the coastlines.

The function has the following arguments:

drawcoastlines(linewidth=1.0, linestyle=”solid”, color=”k”, antialiased=1, ax=None, zorder=None)

- linewidth sets, of course, the line width in pixels

- linestyle sets the line type. By default is solid, but can be dashed, or any matplotlib option

- color is k (black) by default. Follows also matplotlib conventions

- antialiased is true by default

- zorder sets the layer position. By default, the order is set by Basemap

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt

    map = Basemap()

    map.drawcoastlines()

    plt.show()
    plt.savefig('test.png')

## drawcounties

Draws the USA counties from the layer included with the library

drawcounties(linewidth=0.1, linestyle=”solid”, color=”k”, antialiased=1, facecolor=”none”, ax=None, zorder=None, drawbounds=False)

- linewidth sets, of course, the line width in pixels

- linestyle sets the line type. By default is solid, but can be dashed, or any matplotlib option

- color is k (black) by default. Follows also matplotlib conventions

- antialiased is true by default

- zorder sets the layer position. By default, the order is set by Basemap

Note

facecolor argument, which is supposed to color the counties, doesn’t seem to work at least in some Basemap versions.

Note that:

- The resolution is fix, and doesn’t depend on the resolution parameter passed to the class constructor

- The coastline is in another function, and the country coasts are not considered coast, which makes necessary to combine the method with others to get a good map

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt

    map = Basemap(llcrnrlon=-93.,llcrnrlat=40.,urcrnrlon=-75.,urcrnrlat=50.,
                 resolution='i', projection='tmerc', lat_0 = 40., lon_0 = -80)

    map.drawmapboundary(fill_color='aqua')
    map.fillcontinents(color='#cc9955', lake_color='aqua')

    map.drawcounties()

    plt.show()

## drawcountries

Draws the country borders from the layer included with the library.

The function has the following arguments:

drawcountries(linewidth=1.0, linestyle=”solid”, color=”k”, antialiased=1, ax=None, zorder=None)

- linewidth sets, of course, the line width in pixels

- linestyle sets the line type. By default is solid, but can be dashed, or any matplotlib option

- color is k (black) by default. Follows also matplotlib conventions

- antialiased is true by default

- zorder sets the layer position. By default, the order is set by Basemap

Note that:

- The resolution indicated when creating the Basemap instance makes the layer to have a better or coarser resolution

- The coastline is in another function, and the country coasts are not considered coast, which makes necessary to combine the method with others to get a good map

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt

    map = Basemap(projection='ortho',
                  lat_0=0, lon_0=0)

    map.drawmapboundary(fill_color='aqua')
    map.fillcontinents(color='coral',lake_color='aqua')

    map.drawcountries()

    plt.show()

Without drawing the coastline, the result is a bit strange:

## drawlsmask

A method that draws at once lakes, land and oceans. Avoids fillcontinents and drawmapboundary. Besides, it can change the data origin to a custom array of points.

A difference from the other methods is that the zorder can’t be set in this method.

drawlsmask(land_color=”0.8”, ocean_color=”w”, lsmask=None, lsmask_lons=None, lsmask_lats=None, lakes=True, resolution=”l”, grid=5, **kwargs)

- land_color sets the color assigned to the land (a gray by default)

- ocean_color sets the colors of the oceans (white by default)

- lsmask An array with alternative data. If None, the default data from the library is taken. The array must contain 0’s for oceans and 1’s for land

- lsmask_lons the longitudes for the alternative land sea mask

- lsmask_lats the latitudes for the alternative land sea mask

- resolution can change the resolution of the data defined by the Basemap instance

- grid The mask array grid resolution in minutes of arc. Default is 5 minutes

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt

    map = Basemap(projection='ortho',
                  lat_0=0, lon_0=0)

    map.drawlsmask(land_color = "#ddaa66",
                   ocean_color="#7777ff",
                   resolution = 'l')

    plt.show()

## drawmapboundary

Draws the earth boundary on the map, with optional filling.

drawmapboundary(color=”k”, linewidth=1.0, fill_color=None, zorder=None, ax=None)

- linewidth sets, of course, the line width in pixels

- color sets the edge color and is k (black) by default. Follows also matplotlib conventions

- fill_color sets the color that fills the globe, and is None by default . Follows also matplotlib conventions

- zorder sets the layer position. By default, the order is set by Basemap

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt

    plt.figure(0)
    map = Basemap(projection='ortho',lon_0=0,lat_0=0,resolution='c')
    map.drawmapboundary()

    plt.figure(1)
    map = Basemap(projection='sinu',lon_0=0,resolution='c')
    map.drawmapboundary(fill_color='aqua')

    plt.show()

Orthographic projection result

Sinusoidal Projection result

## drawmeridians

Draws the meridians on the map

drawmeridians(meridians, color=”k”, linewidth=1.0, zorder=None, dashes=[1, 1], labels=[0, 0, 0, 0], labelstyle=None, fmt=”%g”, xoffset=None, yoffset=None, ax=None, latmax=None, **kwargs)

- meridians is a list with the longitudes to plot. This can be created with range() if the values are integers. If you need floats, np.arange() is a good option

- color sets the color of the line. This page explains all the color options

- linewidth sets, of course, the line width in pixels

- zorder changes the position of the lines, to be able, for instance, to make the land to cover the meridians, or the opposite

- Sets the dashing style. The first element is the number of pixels to draw, and the second, the number of pixels to skip

- labels change the positions where the labels are drawn. Setting the value to 1 makes the labels to be drawn at the selected edge of the map. The four positions are [left, right, top, bottom]

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt

    map = Basemap(projection='aeqd',
                  lon_0=0.0, lat_0=0,
                  width=25000000, height=25000000)

    map.drawmeridians(range(0, 360, 20))

    plt.show()

This example shows the simplest way to use the function, using the Azimuthal equidistant projection. To see a more complex example, take a look at drawparallels

## drawparallels

Draws the parallels on the map

drawparallels(circles, color=”k”, linewidth=1.0, zorder=None, dashes=[1, 1], labels=[0, 0, 0, 0], labelstyle=None, fmt=”%g”, xoffset=None, yoffset=None, ax=None, latmax=None, **kwargs)

- parallels is a list with the longitudes to plot. This can be created with range() if the values are integers. If you need floats, np.arange() is a good option

- color sets the color of the line. This page explains all the color options

- linewidth sets, of course, the line width in pixels

- zorder changes the position of the lines, to be able, for instance, to make the land to cover the parallels, or the opposite

- Sets the dashing style. The first element is the number of pixels to draw, and the second, the number of pixels to skip

- labels change the positions where the labels are drawn. Setting the value to 1 makes the labels to be drawn at the selected edge of the map. The four positions are [left, right, top, bottom]

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt

    map = Basemap(projection='poly',
                  lon_0=0.0, lat_0=0,
                  llcrnrlon=-80.,llcrnrlat=-40,urcrnrlon=80.,urcrnrlat=40.)

    map.drawmapboundary(fill_color='aqua')
    map.fillcontinents(color='coral',lake_color='aqua')
    map.drawcoastlines()

    map.drawparallels(range(-90, 100, 10), linewidth=2, dashes=[4, 2], labels=[1,0,0,1], color='r', zorder=0 )
    plt.show()

The example shows some avance functions, such as labeling or zorder, using the polyconic projection. To see a simpler example, take a look ar drawmeridians

## drawrivers

Draws the rivers from the layer included with the library.

drawrivers(linewidth=0.5, linestyle=”solid”, color=”k”, antialiased=1, ax=None, zorder=None)

- linewidth sets, of course, the line width in pixels

- linestyle sets the line type. By default is solid, but can be dashed, or any matplotlib option

- color is k (black) by default. Follows also matplotlib conventions

- antialiased is true by default

- zorder sets the layer position. By default, the order is set by Basemap

Note that:

- The resolution is fix, and doesn’t depend on the resolution parameter passed to the class constructor

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt

    map = Basemap(llcrnrlon=-93.,llcrnrlat=40.,urcrnrlon=-75.,urcrnrlat=50.,
                 resolution='i', projection='tmerc', lat_0 = 40., lon_0 = -80)

    map.drawmapboundary(fill_color='aqua')
    map.fillcontinents(color='#ddaa66', lake_color='#0000ff')

    map.drawcountries()
    map.drawrivers(color='#0000ff')

    plt.show()

## drawstates

Draws the American countries states borders from the layer included with the library. Draws also the Australian states.

drawstates(linewidth=0.5, linestyle=”solid”, color=”k”, antialiased=1, ax=None, zorder=None)

- linewidth sets, of course, the line width in pixels

- linestyle sets the line type. By default is solid, but can be dashed, or any matplotlib option

- color is k (black) by default. Follows also matplotlib conventions

- antialiased is true by default

- zorder sets the layer position. By default, the order is set by Basemap

Note that:

- The resolution is fix, and doesn’t depend on the resolution parameter passed to the class constructor

- The country border is not drawn, creating a strange effect if the method is not combined with drawcountries

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt

    map = Basemap(width=12000000,height=9000000,
                rsphere=(6378137.00,6356752.3142),\
                resolution='l',area_thresh=1000.,projection='lcc',\
                lat_1=45.,lat_2=55,lat_0=50,lon_0=-107.)

    map.drawmapboundary(fill_color='aqua')
    map.fillcontinents(color='#ddaa66', lake_color='aqua')

    map.drawcountries()
    map.drawstates(color='0.5')

    plt.show()

## etopo

Plots a relief image called etopo taken from the NOAA. The image has a 1”” arch resolution, so when zooming in, the results are quite poor.

etopo(ax=None, scale=None, **kwargs)

- The scale is useful to downgrade the original image resolution to speed up the process. A value of 0.5 will divide the size of the image by 4

- The image is warped to the final projection, so all projectinos work properly with this method

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt

    map = Basemap(llcrnrlon=-10.5,llcrnrlat=33,urcrnrlon=10.,urcrnrlat=46.,
                 resolution='i', projection='cass', lat_0 = 39.5, lon_0 = 0.)

    map.etopo()

    map.drawcoastlines()

    plt.show()

## fillcontinents

Draws filled polygons with the continents

fillcontinents(color=”0.8”, lake_color=None, ax=None, zorder=None, alpha=None)

- color sets the continent color. By default is a gry color. This page explains all the color options

- lake color sets the color of the lakes. By default doesn’t draw them, but you may set it to aqua to plot them blue

- alpha is a value from 0 to 1 to set the transparency

- zorder sets the position of the layer related to others. It can be used to hide (or show) a contourf layer, that should be only on the sea, for instance

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt

    map = Basemap(projection='ortho',
                  lat_0=0, lon_0=0)

    #Fill the globe with a blue color
    map.drawmapboundary(fill_color='aqua')
    #Fill the continents with the land color
    map.fillcontinents(color='coral',lake_color='aqua')

    map.drawcoastlines()

    plt.show()

## shadedrelief

Plots a shaded relief image. The origin is the www-shadedrelief.com web page. The original image size is 10800x5400

shadedrelief(ax=None, scale=None, **kwargs)

- The scale is useful to downgrade the original image resolution to speed up the process. A value of 0.5 will divide the size of the image by 4. The original size is quite big, 10800x5400 pixels

- The image is warped to the final projection, so all projections work properly with this method

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt

    map = Basemap(llcrnrlon=-10.5,llcrnrlat=33,urcrnrlon=10.,urcrnrlat=46.,
                 resolution='i', projection='cass', lat_0 = 39.5, lon_0 = 0.)

    map.shadedrelief()

    map.drawcoastlines()

    plt.show()

## warpimage

Displays an image as a background.

warpimage(image=”bluemarble”, scale=None, **kwargs)

- By default, displays the NASA Bluemarble image

- The image must be in latlon projection, so the x size must be double than the y size

- The image must cover the whole world, with the longitude starting at -180

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt
    import Image

    map = Basemap(projection='ortho',
                  lat_0=0, lon_0=0)

    tmpdir = '/tmp'

    size = [600, 300]
    im = Image.open("../sample_files/by.png")

    im2 = im.resize(size, Image.ANTIALIAS)
    im2.save(tmpdir+'/resized.png', "PNG")

    map.warpimage(tmpdir+'/resized.png')

    map.drawcoastlines()

    plt.show()

- The image must be resized to fit the proportions. The script won’t work if the computer hasn’t got the /tmp directory.

## wmsimage

Downloads and plots an image, using the WMS protocol

wmsimage(server, xpixels=400, ypixels=None, format=”png”, verbose=False, **kwargs)

Note

Many arguments aren’t documented, making this method a little bit difficult to use

- server can be used to connect to another server using the same REST API

- xpixels actually sets the zoom of the image. A bigger number will ask a bigger image, so the image will have more detail. So when the zoom is bigger, the xsize must be bigger to maintain the resolution

- ypixels can be used to force the image to have a different number of pixels in the y direction that the ones defined with the aspect ratio. By default, the aspect ratio is maintained, which seems a good value

- format sets the image format to ask at the WMS server. Usually, the possibilities are png/gif/jpeg.

- verbose prints the url used to get the remote image. It’s interesting for debugging, since prints all the available layers, projections in EPSG codes, and other information

The problem is that using only these parameters won’t add the layer properly. There are more mandatory arguments:

- layers is a list of the WMS layers to use. To get all the possible layers, take a look at the WMS GetCapabilities or, easier, use verbose=True to print them

    - When the layer name has a space, the method won’t work or, at least, I couldn’t make it work. Unfortunately, many services offer layers with spaces in its name

- styles is a list with the styles to ask to the WMS service for the layers. Usually will work without this parameter, since the server has usually default styles

- Other parameters, such as date, elevation or colorscale have the same names and do the same things as in the WMS standard

- An other important point when using this method is that the projection must be set using the epsg argument, unless 4326, or cyl in Basemap notation is used. To see how to set a projection this way, see the section Using epsg to set the projection

Note

The method requires OWSLib. To install it, just type sudo pip install OWSLib

The Basemap test files shows how to use the method quite well.

    from mpl_toolkits.basemap import Basemap
    import matplotlib.pyplot as plt

    map = Basemap(llcrnrlon=8.35,llcrnrlat=41.225,urcrnrlon=10.01,urcrnrlat=43.108,
                  projection='cyl', epsg=4326)

    wms_server = "http://www.ga.gov.au/gis/services/topography/Australian_Topography/MapServer/WMSServer"
    wms_server = "http://wms.geosignal.fr/metropole?"

    map.wmsimage(wms_server, layers=["Communes", "Nationales", "Regions"], verbose=True)
    plt.show()

The source of the map data is http://www.geosignal.org, which has many layers for France.