mapoutline

Outline of georeferenced image or data grid

Syntax

[x,y] = mapoutline(R,sizeA)

[x,y] = mapoutline(R,h,w)

[x,y] = mapoutline(___,"close")

mat = mapoutline(___)

Description

[x,y] = mapoutline(R,sizeA) calculates the xy-coordinates of the rectangle that outlines the specified map raster reference object. The sizeA argument specifies the size of the image or data grid that is associated with the reference object.

[x,y] = mapoutline(R,h,w) specifies the height and width of the image or data grid, such that [h w] = [sizeA(1) sizeA(2)].

[x,y] = mapoutline(___,"close") closes the rectangle by appending the first elements of x and y to the ends of x and y.

mat = mapoutline(___) returns the xy-coordinates of the rectangle, such that mat = [x y].

Examples

Calculate Outline of Georeferenced Image

Read a GeoTIFF image of Boston as an array and a map cells reference object.

[A,R] = readgeoraster("boston.tif");

Calculate the xy-coordinates of the rectangle that outlines the image. Close the rectangle by specifying the "close" option.

sizeA = R.RasterSize;
[x,y] = mapoutline(R,sizeA,"close")

x = 5×1
105 ×

    7.6432
    7.6432
    7.7902
    7.7902
    7.6432

y = 5×1
106 ×

    2.9606
    2.9511
    2.9511
    2.9606
    2.9606

Display the image and the outline by using the mapshow function. Use a thick, red line for the outline. Improve the visibility of the outline by zooming out.

figure
mapshow(A,R,DisplayType="image")
mapshow(x,y,DisplayType="line",Color="r",LineWidth=3)

xlim([762000 780000])
ylim([2950000 2963000])

Input Arguments

R — Raster reference

MapCellsReference object | MapPostingsReference object

Raster reference, specified as a MapCellsReference object or a MapPostingsReference object.

sizeA — Size of image or data grid

two-element vector

Size of the image or data grid that is associated with R, specified as a two-element vector of the form [h w], where h is the height and w is the width. You can find this value by querying the RasterSize property of R.

Data Types: double

h — Height of image or data grid

numeric scalar

Height of the image or data grid that is associated with R, specified as a numeric scalar.

Data Types: double

w — Width of image or data grid

numeric scalar

Width of the image or data grid that is associated with R, specified as a numeric scalar.

Data Types: double

Output Arguments

x — x-coordinates of rectangle that outlines R

four-element column vector | five-element column vector

x-coordinates of the rectangle that outlines R, returned as one of these values:

• A four-element column vector, when you do not specify the "close" option.

• A five-element column vector, when you specify the "close" option. The first and last elements of the vector are equal.

y — y-coordinates of rectangle that outlines R

four-element column vector | five-element column vector

y-coordinates of the rectangle that outlines R, returned as one of these values:

• A four-element column vector, when you do not specify the "close" option.

• A five-element column vector, when you specify the "close" option. The first and last elements of the vector are equal.

mat — xy-coordinates of rectangle that outlines R

4-by-2 matrix | 5-by-2 matrix

xy-coordinates of the rectangle that outlines R, returned as one of these values:

• A 4-by-2 matrix, when you do not specify the "close" option.

• A 5-by-2 matrix, when you specify the "close" option. The first and last rows of the matrix are equal.

Alternative Functionality

Create an area of interest (AOI) from a MapCellsReference or MapPostingsReference object by using the aoiquad function. An AOI is a mappolyshape or geopolyshape object that defines a focus area for geospatial analysis and visualization. For more information about AOIs, see Define Areas of Interest.

Version History

Introduced before R2006a

R2024b: mapoutline does not accept referencing matrices as input

The mapoutline function does not accept referencing matrices as input. Use a map raster reference object (specified as a MapCellsReference or MapPostingsReference object) as input instead. If using a geographic raster reference object (specified as a GeographicCellsReference or GeographicPostingsReference object) as input, you must replace uses of the mapoutline function with the outlinegeoquad function. Reference objects have several advantages over referencing matrices.

• Unlike referencing matrices, reference objects have properties that document the size of the associated raster, its world limits, and the direction of its rows and columns.

• You can manipulate the limits of rasters associated with reference objects using the mapcrop function.

• You can manipulate the size and resolution of rasters associated with reference objects using the mapresize function.

The strategy you use to update your code depends on whether your data is in planar or geographic coordinates.

Planar Map Coordinates

If the referencing matrix is in planar map coordinates, create a map reference object and use a different syntax of the mapoutline function.

• Create a map reference object for a raster of cells by using the maprefcells function.

• Create a map reference object for a raster of regularly posted samples by using the maprefpostings function.

• Alternatively, you can convert from a referencing matrix to a map reference object by using the refmatToMapRasterReference function.

Once you have created a reference object, replace uses of the mapoutline function in your code with the syntax [X,Y] = mapoutline(R,R.RasterSize), where R is the reference object.

Geographic Coordinates

If the referencing matrix is in geographic coordinates, create a geographic reference object and replace uses of the mapoutline function with the outlinegeoquad function.

• Create a geographic reference object for a raster of cells by using the georefcells function.

• Create a geographic reference object for a raster of regularly posted samples by using the georefpostings function.

• Convert from a referencing matrix to a geographic reference object by using the refmatToGeoRasterReference function.

Once you have created a reference object, replace uses of the mapoutline function in your code with the outlinegeoquad syntax [LAT,LON] = outlinegeoquad(R.LatitudeLimits,R.LongitudeLimits), where R is the reference object.

R2024b: mapoutline does not accept structure arrays as input

The mapoutline function does not accept structure arrays as input, including structure arrays containing RefMatrix, Height, and Width fields. Use a map raster reference object as input instead.

To update your code, convert the structure array to a reference object by using the refmatToMapRasterReference function. Then, replace uses of the mapoutline function with the syntax [X,Y] = mapoutline(R,R.RasterSize), where R is the reference object.

To Be Removed	Recommended
[X,Y] = mapoutline(INFO);	R = refmatToMapRasterReference(INFO.RefMatrix, ... [INFO.Height INFO.Width]); [X,Y] = mapoutline(R,R.RasterSize);