| Version 2.7 (R2008a) Mapping Toolbox™ Software Release Notes | |
This table summarizes what's new in Version 2.7 (R2008a):
New Features and Changes | Version Compatibility Considerations | Fixed Bugs and Known Problems | Related Documentation at Web Site |
|---|---|---|---|
Yes | Yes — Details labeled as Compatibility Considerations in descriptions of new features and changes, below. See also Summary. | Bug reports at Web site | Printable Release Notes: PDF Current product documentation |
New Longitude-Wrapping Option in the closePolygonParts Utility
Removed Syntaxes that Returned Error Messages in Optional Argument
A geographic quadrangle is an area on the surface of a sphere or ellipsoid bounded on the east and west by a pair of meridians and on the north and south by a pair of parallels. In many ways, such an object is similar to a bounding rectangle in the plane, but they can be difficult to work with because of the way longitudes wrap around and the way meridians converge at the poles. For example,
The western longitude limit can have a larger numerical value than the eastern longitude limit.
If one of the bounding latitudes is +90 or -90 degrees, the quadrangle has thee sides rather than four.
As noted below, the intersection of two geographic quadrangles might possibly comprise two separate parts—with the eastern end of the first quadrangle intersecting the western end of the second quadrangle, and vice versa.
Mapping Toolbox software typically represents a geographic quadrangle in terms of its latitude and longitude limits, stored in 1-by-2 vectors having the forms
latlim = [southern_limit northern_limit] lonlim = [western_limit eastern_limit]
Vectors like these have been used in various Mapping Toolbox functions since its inception, and can appear in the input or output argument lists of over dozen functions.
In R2008a, three new functions let you query, intersect, and display geographic quadrangles, and account for subtleties such as those described above:
ingeoquad — Returns true for points inside or on latitude-longitude quadrangle
intersectgeoquad — Returns intersection(s) of two latitude-longitude quadrangles
outlinegeoquad — Returns sampled polygon vertices for a latitude-longitude geographic quadrangle
Use ingeoquad, for example, to check whether a geographic point is located within the area covered by a regular data grid, given the latitude and longitude limits computed by limitm.
Use intersectgeoquad to compute overlap, if any, between two quadrangles. Interestingly, three general results are possible: no intersection, an intersection that is itself a geographic quadrangle, and an intersection the comprises two distinct geographic quadrangles. (The intersection can have two parts if the input quadrangles wrap around in longitude to overlap on both their eastern and western sides. This case, of course, is not possible for bounding boxes in the plane.)
Use outlinegeoquad to generate a pair of latitude and longitude coordinate vectors that define a polygon that traces the outline of a geographic quadrangle. This can be useful for displaying the quadrangle graphically using geoshow, for example, especially on a projection where the meridians and/or parallels do not project to straight lines, because in addition to connecting the four corners outlinegeoquad lets you interpolate additional vertices along parallels, meridians, or both.
Function avhrrgoode has been rewritten to improve its efficiency and to remove a number of problems and limitations:
Fixed a spatial referencing problem when a nonglobal region has been specified which caused locations to be offset by half a pixel.
The function no longer returns incorrect NaN coordinate values at the equator when given certain latitude limits that cross the equator.
The function no longer errors when attempting to read a file name with certain legal latitude and longitude limits.
The new version executes at least five times faster.
The nonfunctional syntaxes avhrrgoode and avhrrgoode(region) have been removed from the documentation.
The function now returns empty when the user-supplied limits are outside data limits.
The function no longer permits longitude limits to be specified outside the interval [-180 180].
Parameters other than region and filename can be specified as empty to use their default values.
In versions prior to R2008a, when reading from the global data set and a smaller region data set, the size of the outputs differed by one column from each other when given identical latitude and longitude limits. Now the sizes are the same.
In previous releases, after calculating the latitude and longitude limits of the geographic quadrangle bounding a regular data grid, function limitm arbitrarily rounded those limits to the nearest one millionth of a degree (equivalent to about 10 cm in latitude or equatorial longitude). Although it is small, this rounding operation in effect applied an arbitrary shift to points on or very near the edge of the grid. The direction of the shift and its magnitude were arbitrary because rounding can either increase or decrease a value. In any given case, the shift depended on the specific referencing vector and the number of columns and rows in the data grid. This behavior unnecessarily degraded the numerical accuracy of limitm and those functions which depend on it, and it has now been removed. For more information, see bug report 420038 on the MathWorks Web site.
In the setpostn function , an identical rounding step has been removed. Additional changes eliminate a problem for certain input points near boundaries between grid cells that caused row and column subscripts returned by setpostn to be off by 1. For points near the northern and eastern edges of the data grid—but still within the grid—returned subscript values could exceed the corresponding grid size. For more information, see bug report 173338 on the MathWorks Web site.
These corrections can cause subtle changes in the behavior of other functions that work with regular data grids referenced to latitude-longitude, for example, imbedm.
If your referencing vector contains approximations to rational numbers that do not have an exact a 64-bit floating point representation (e.g., for cells that are 1.5 degrees wide, refvec(1) is 0.666666...), you may still find that certain points that are extremely close to a grid cell boundary cross into a neighboring cell just across the boundary. Such numerical ambiguity is inevitable given how the information in a referencing vector is encoded. Although it cannot be eliminated within setpostn, the inexactness only affects points that fall within a few factors of eps (very much less than a millionth of a degree) away from a given cell boundary.
The Mapping Toolbox demo data in the $MATLABROOT/toolbox/map/mapdemos directory now includes a global tsunami data set in shapefile format with 'Point' geometry. The data set comprises four files:
tsunamis.dbf tsunamis.shp tsunamis.shx tsunamis.txt
tsunamis.txt is not part of the shapefile set. It is a text file documenting the data set.
The data includes tidal wave events for which the maximum water height was at least one meter, ranging for the years 1950 to 2006, inclusive. The Global Tsunami Database, U.S. National Geospatial Data Center (NGDC), National Oceanic and Atmospheric Administration (NOAA), available at http://www.ngdc.noaa.gov/seg/hazard/tsu.shtml, is the source of the data. All the files consist of U.S. Government information that is in the public domain and is not subject to copyright protection.
The approximate location of each event is a single point in geodetic coordinates (latitude-longitude) with an unspecified datum. The .dbf file contains 18 separate text or numeric attributes for most events, including wave height, causes and seismic magnitudes, and location and country names.
The shapefiles were created at The MathWorks™ from querying the online source data, importing the results into the MATLAB workspace, and exporting them using the Mapping Toolbox shapewrite function. For more information, type
edit tsunamis.txt
at the MATLAB prompt.
The changes described in the Versin 2.6 (R2007b) release note Improvements to Data Trimming in patchm and patchesm resulting from improved polygon trimming also apply to the fillm function.
The angl2str function once again can format strings for angles in degrees-minutes (DM) and degrees-minutes-second (DMS) notations. These options were removed in Version 2.6 (R2007b), and have now been restored. In addition to the 'degrees' and 'radians' units options, you can now obtain DM- and DMS-formatted strings by specifying
'degrees2dm' — for degrees-decimal minutes formatting
'degrees2dms' — for degrees-minutes-decimal seconds formatting
To use these options, input angles must be in degrees. That is, angl2str uses the string units to indicate both the units in which the angle argument is provided and to control the output format.
This change restores the behavior of angl2str prior to Version 2.6 in a slightly different form. Before V. 2.6, the DM and DMS options were specified by a units strings of 'dm' and 'dms', respectively. The new strings that replace them signify that the functions degrees2dm and degrees2dms, introduced in Version 2.5 (R2007a), perform the conversions of inputs given in degrees to DM and DMS notation.
The closePolygonParts function now accepts an optional third argument, angleunits, that must be string-valued and can be either 'degrees' or 'radians'. If you include this argument with a value appropriate for the first two (lat, lon) arguments, closePolygonParts can correctly account for longitude wrapping. For example, a polygon that begins at a given latitude with a longitude of -180 degrees, and ends at the same latitude with a longitude of 180 degrees is regarded as closed and an additional vertex is not added.
From Version 2.0 onward, the Mapping Toolbox documentation has referred to "version 1 geographic data structures" and "version 2 geographic data structures," using the terms "geostruct1" and "geostruct2" respectively as shorthand for them. To reflect current usage, starting with this version of the toolbox, these terms are obsolete; new terms and distinctions have been defined to help clarify what these structures are and can be used for:
Geographic data structure arrays, introduced in Version 2.0, contain vector features and are called either
Geostructs, if they contain geographic coordinates (latitudes and longitudes)
Mapstructs, if they contain projected map/planar coordinates (x and y)
Display structure arrays, dating from Version 1, also used to be called geographic data structures, and can contain either vector features or raster geodata.
Due to their greater generality, geostructs and mapstructs are the preferred form in which to represent vector features in the toolbox. The preferred way to package raster geodata is with regular or geolocated data grids (2-D numeric arrays accompanied by referencing matrices or vectors). There are only a few Mapping Toolbox functions that can still generate display structures (by importing data from external file formats):
dcwdata — Returns line/patch display structures
dcwgaz — Returns line/patch display structures
demdataui — Returns "regular"—as in regular data grid, that is—display structures
mlayers — GUI to control plotting of display structure elements
tgrline — Returns line/patch display structures
vmap0data — Returns line/patch display structures
vmap0ui — GUI for selecting data from Vector Map Level 0
Even fewer functions accept display structures as inputs:
displaym — Displays elements of a display structure
extractm — Extracts lat-lon coordinates from line/patch display structure
In addition to displaym and extractm, the updategeostruct function converts a line or patch display structure to a geostruct.
For more information, see Mapping Toolbox Geographic Data Structures.
All warnings issued from within Mapping Toolbox functions now include identifiers, enabling you to suppress them at your own discretion. Previously, this was possible for only certain warnings, but with the addition of new identifiers in over two dozen functions in R2008a, all warnings are now covered. For example, you can turn off the warning that setpostn issues when given a latitude-longitude position outside the limits of the specified data grid. In this case, the warning identifier is
'map:setpostn:pointOutsideLimits'
You can suppress it using the following statement:
warnstate = warning('off','map:setpostn:pointOutsideLimits');Then, after making your call to setpostn, you can restore the original warning state with
warning(warnstate);
See the MATLAB warning function reference page for the for more information on turning warnings off and on and managing the warning state.
The reference pages for following functions, which themselves were removed in R2007b, have been removed from the Mapping Toolbox User's Guide:
tigerp — Read TIGER p and pa thinned boundary files (ArcInfo format)
tigermif — Read the TIGER MIF thinned boundary file (MapInfo format)
See the R2007b release note Functions tigermif and tigerp Are Obsolete and Error if Used for alternatives to tigermif and tigerp.
In earlier versions, the following Mapping Toolbox functions supported syntaxes that included an optional output argument called msg. If this output argument was included in a call to one of these functions, and certain error conditions were encountered while executing the function, then instead of issuing an error, the function would return the corresponding error message in msg. The following functions are affected:
axesm
defaultm
displaym
gcm
handlem
lightm
linem
maps
meshm
namem
patchesm
roundn
surfacem
surflsrm
textm
unitstr
utmzone
utmzoneui
For example, even with no map axes present, the command
[mstruct, msg] = gcm
returned without error in R2007b and earlier, but placed an error message string in msg.
These syntaxes have been disabled in R2008a. If you try to use them, a warning is issued. The warning may be followed by an error, depending on whether or not an error condition is encountered within the function. For example, if a map axes is present, the command above results in
Warning: Function GCM no longer returns error message strings in output argument MSG. Instead any errors are thrown where they occur. You should remove the last output argument (MSG) from your call to GCM in order to avoid this warning. If you want to handle errors yourself, call GCM in a try-catch block. > In mapdisp/private/warnObsoleteMSGSyntax at 6 In gcm at 20
If there is no map axes, it results in
Warning: Function GCM no longer returns error message strings in
output argument MSG. Instead any errors are thrown where they occur.
You should remove the last output argument (MSG) from your call to
GCM in order to avoid this warning. If you want to handle errors
yourself, call GCM in a try-catch block.
> In mapdisp/private/warnObsoleteMSGSyntax at 6
In gcm at 20
??? Error using ==> gcm>checkaxes at 41
No axes in current figure.
Select a figure with map axes or use AXESM to define one.
Error in ==> gcm at 24
h = checkaxes(varargin{:});As suggested by this warning, if you have any scripts or functions of your own that depend on the old syntax, you should remove the msg argument and place the function call in a try-catch block instead.
| Version 2.7.1 (R2008b) Mapping Toolbox Software | Version 2.6 (R2007b) Mapping Toolbox Software | |
| © 1984-2009- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |