mapview

Interactive map viewer

Syntax

mapview

Description

mapview opens the Map Viewer app in an empty state. Use the Map Viewer to view geospatial data in map (x-y) coordinates. The Map Viewer works with vector, image, and raster data grids in a map coordinate system. You can load data, pan and zoom on the map, control the map scale of your screen display, control the order, visibility, and symbolization of map layers, annotate your map, and click to learn more about individual vector features. mapview complements mapshow and geoshow, which are for constructing maps in ordinary figure windows in a less interactive, script-oriented way.

For usage information, see the following sections. You can also work through the Map Viewer tutorial, Tour Boston with the Map Viewer App.

Importing Data

The Map Viewer opens with no data loaded and an empty map display window. The first step is to import a data set. Use the options in the File menu to select data from a file or from the MATLAB^® workspace:

Import From File

Use the file browsing dialog to open a file in one of the following formats: Shapefile, GeoTIFF, SDTS DEM, Arc ASCII Grid, TIFF, JPEG, or PNG with world file. This option imports the data into the viewer but does not add it to your workspace.

To view standard-format geodata files provided with the toolbox, set your working folder or navigate the Map Viewer Open dialog to matlabroot/examples/map/data or matlabroot/toolbox/map/mapdata.

Import From Workspace

Images. Use the Raster Data > Image import dialog to select a Referencing matrix or object name and Raster data name for the image from the list of workspace variables. If the image type is truecolor (RGB), specify which band represents the red, green, and blue intensities. (The RasterInterpretation of the referencing object must be 'cells'.)

Data grids. Use the Raster Data > Grid import dialog to select X and Y geolocation and data grid array names from the list of workspace variables.

Vector data. Use the Vector Data > Map coordinates import dialog to select X and Y variables for map coordinates from the list of workspace variables and identify the type of geometry to be displayed (Point, Line, or Polygon). The X and Y variables can specify multiple line segments or multiple polygons if they contain NaNs at matching locations in the coordinate vectors.

Vector geographic data structure. Use the Vector Data > Geographic data structure import dialog to select the structure that contains vector map data from the list of workspace variables.

Once you import your first data set, the Map Viewer automatically sets the limits of its map display window to the spatial extent of the imported data.

Working in Map Coordinates

As you move any of the Map Viewer cursors across the map display area, the coordinate readout in the lower left corners shows you the cursor position in map X and Y coordinates.

The Map Viewer requires that all currently viewed data sets possess the same coordinate system and length units. This is likely to be the case for data sets that originated from a common source. If it is not the case, you will need to adjust coordinates before importing data into the Map Viewer.

If some or all of your data is in geographic coordinates, use projfwd to project latitudes and longitudes to your desired map coordinate system before you import it. When starting from a different projection, you must first unproject to latitude and longitude using projinv, then reproject with projfwd. You might also need to adjust the horizontal datum of your data using, for example, the free GEOTRANS (Geographic Translator) application from the Geospatial Sciences Division of the U.S. National Geospatial-Intelligence Agency (NGA). If you simply need a change of units, multiply by the appropriate conversion factor obtained from unitsratio.

mapview can also display data in unprojected geographic coordinates, if you consistently substitute longitude for map X and latitude for map Y. Geographic coordinates must be consistently expressed in either degrees or radians (not both at once). When using geographic coordinates, do not specify the viewer's map units (see below); you can only use the Map Viewer's map scale display when working in linear units of length.

Setting Map Units and Scale

If you tell the Map Viewer which length unit you are using, it can calculate an approximate map scale for your onscreen display. Set the map units with either the drop-down menu at the bottom of the display or the Set Map Units item in the Tools menu.

The scale computed by the Map Viewer is displayed in the window just above the map units drop-down. To change your display scale while keeping the center of the map display fixed, simply edit this text box.

Make sure to format your text in the standard way (1:N, where N is a positive number such that a distance on the ground is N times the same distance on your screen, e.g., 1:24000).

The scale is approximate because it depends on the MATLAB estimate of the size of your screen pixels. It is also approximate if your projection introduces significant distortion. If your data falls in a fairly small area and you use a conformal projection (e.g., UTM with all data in a single zone), the scale will be very consistent across your entire map.

Navigating Your Map

By default, the Map Viewer sets the limits of your map window to match the extent of the first data set that you load. You will probably want to adjust this to see some areas in greater detail.

The Map Viewer provides several tools to control the limits of your map window and the map scale of the data display. Some are familiar from standard MATLAB figure windows.

Zoom in: Drag a box to zoom in on a specific area or click a point to zoom in with that point centered in the map display.
Zoom out: Click a point to zoom out with that point centered in the map display.
Pan tool: Click, hold, and drag to reposition the selected point in the display window, while holding the map scale fixed. Release when you are satisfied with new display limits.
Fit to window: Set the map display to enclose all currently loaded data layers. This is equivalent to selecting Fit to Window in the View menu.
Back to previous view: Click this button once to return the map scale and display center to their values prior to the most recent zoom, pan, or scale change. Click repeatedly to undo earlier changes. This is equivalent to selecting Previous View in the View menu.

Another way to zoom in or out while keeping the center of the view fixed at the same map coordinates is to directly edit the map scale box at the bottom of the screen.

Managing Map Layers

Each time you import a set of vectors, an image, or a data grid into the Map Viewer, the new data is stored in a new map layer. The layers form an ordered stack. Each layer is listed as an item in the Layers menu, with its position in the menu indicating its position in the stack.

When you import a new layer, the Map Viewer automatically places it at the top of the layer stack. To reposition a layer in the stack, select it in the Layers menu, slide right, and select To Top, To Bottom, Move Up, or Move Down from the pop-up submenu.

The vector features or raster in a given layer obscure coincident elements of any underlying layers. To control layers that are obscuring one another, you can also toggle layer visibility on and off. Use the item Visible in the slide-right menu. Or, simply remove a layer from the Map Viewer via the Remove item in the slide-right menu. Remember that even if a layer's visibility is on, the layer does not appear if its contents are located completely outside the current display limits or are obscured by another layer.

Symbolizing Vector Features

When point, line, and polygon layers are loaded, the Map Viewer initializes their graphics properties as follows:

Geometry	Properties
Point (line objects)	`LineStyle = 'none Marker = 'x' MarkerEdgeColor =` <randomly generated value> `MarkerFaceColor = 'none`'
Line (line objects)	`Color =` <randomly generated value> `LineStyle = '-' Marker = 'none'`
Polygon (patch objects)	`EdgeColor = [0 0 0] FaceColor =` <randomly generated value>

To override symbolism defaults for a vector layer, use makesymbolspec to create a symbol specification in the workspace. A symbolspec contains a set of rules for setting vector graphics properties based on the values of feature attributes. For instance, if you have a line layer representing roads of various classes (e.g., major highway, secondary road, etc.), you can create a symbolspec to use a different color, line width, or line style for each road class. See the makesymbolspec help for examples and to learn how to construct a symbolspec. If you regularly work with data sets sharing a common set of feature attributes, you might want to save one or more symbolspecs in a MAT-file (or save calls to makesymbolspec in a MATLAB program file).

Once you have a symbolspec in your workspace, select your vector layer in the Layers menu, then slide right and click Set Symbol Spec, which opens a dialog box. Use the dialog box to select the symbolspec from your workspace.

Getting Information About Vector Features

The Datatip tool and the Info tool provide different ways to check the attributes of vector features that you select graphically. Before using either tool you must designate one of your vector layers as active. (The default active layer is the first one that you imported.) Either use the Active Layer drop-down menu at the bottom of your screen or select the layer in the Layers menu, slide right, and select Active. Having a designated active layer ensures that when you click a feature you don't inadvertently select an overlapping feature from a different layer.

Datatip tool: The Datatip tool displays a feature attribute in a text label each time you click a vector feature. By default the attribute is the first one in the layer's attribute list. To change which attribute is used, select the layer in the Layers menu, slide right, and click Set Layer Attribute. In the dialog that follows, select a different attribute, or Index. If you choose Index, the Map Viewer displays the one-based index value corresponding to a given feature—based on its position in the input file or workspace array. To remove a text label, right-click it and choose Delete datatip from the context menu. Or choose Delete all datatips from the context menu or the Tools menu.
Info tool: The Info tool opens a separate text window each time you click a vector feature. The window displays all the attribute names and values for that feature, in contrast to the Datatip tool, which displays only the value of a single attribute. If you need to compare two or more features, simply click each one and view the info windows together. Use its close button to close an info window when you're done with it, or choose Close All Info Windows from the Tools menu.

Annotating Your Map

Use the text, line, or arrow annotation tools to mark and highlight points of interest on your map, or select the corresponding items in the Insert menu. Use the Select annotations tool and Edit menu to modify or remove your annotations. The Map Viewer manages annotations separately from data layers; annotations always stay on top. Note that annotations cannot be saved as graphic objects, although you can export maps containing annotations to an image format as described below.

Creating and Using Additional Views

Use New View on the File menu to create an additional Map Viewer window linked to an existing window. Consider using an additional window when you want to see your map at different scales at the same time (e.g., a detailed view plus an overview), or when you want to simultaneously see different areas of the map at large scale. You can create as many additional windows as you need, and close them when you want. Your mapview session ends when you close the last window.

Options for creating a new viewer window include: Duplicate Current View, Full Extent, Full Extent of Active Layer, and Selected Area. Click and drag with the Select area tool to define a selected area.

A new viewer window differs from existing windows mainly in terms of the visible map extent and scale (it also omits annotations and any labels you added with the datatip tool). You will see the same layers in the same order with the same settings (including the active layer). Updates to layers (insertion/removal, order, visibility, label attribute, and symbolization) in one viewer window are propagated automatically to all the windows with which it is linked. Updates to annotations and datatip labels are not propagated between viewers. If you need two different layer configurations in different windows, launch a second mapview from the command line instead of creating an additional window. The views it contains will not be linked to previous ones.

Exporting Your Map

The Map Viewer allows you to export all or part of your map for use in a publication or on a Web page. Use File > Save As Raster Map to export an image of either the current display extent or an area outlined with the Select area tool. Select a format (PNG, TIFF, JPEG) from the drop-down menu in the export dialog. For maps including vector layers, PNG (Portable Network Graphics) is often the best choice. This format provides excellent quality, good compression, and is well supported by modern Web browsers. The export process automatically creates a world file (ending with suffix tfw, jgw, or pgw) as well; the pair of files constitute a georeferenced image that itself can be displayed with mapview, mapshow, and many external GIS packages.

Limitations

The Select area tool is not supported in MATLAB Online™. To view a particular region on the map, use the Zoom in, Zoom out, and Pan tools instead.

Documentation