This table summarizes what's new in Version 2.6 (R2007b):
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 | No |
- Exporting Vector Geodata to Earth Browsers
- Improved Conversion Between Angle Units
- Improvements in Handling Length Units
- New Angle Wrapping Functions
- New Function to Unwrap Sequences of Angles
- Improvements to Data Trimming in patchm and patchesm
- Higher Quality boston.tif GeoTIFF Satellite Image
- Map Axes Now Display Transparent Objects More Easily
- The arcgridread Function Now Imports Noninteger Data Grids
- Change to avhrrlambert Function Behavior When No Data Is Available
- Enhancements to Mapping Toolbox User's Guide
- Functions deg2rad and rad2deg No Longer Convert Complex to Real
- Degrees-Minutes-Seconds Conversion Functions Are Obsolete and Error if Used
- Time Conversion Functions Are Obsolete and Error if Used
- cmapui GUI is now Obsolete
- Functions tigermif and tigerp Are Obsolete and Error if Used
Exporting Vector Geodata to Earth Browsers
kmlwrite is a new function for exporting vector point data to a file in KML format. KML stands for Keyhole Markup Language; it is an XML dialect used to structure geographic data for display in an Earth browser, such as Google™ Earth, Google Maps, and Maps for Google Mobile. KML has a hierarchical structure of nested elements and attributes. kmlwrite has a simple API that lets Mapping Toolbox users write vector data to a KML file in order to subsequently display the data onto an Earth browser.
When used with Google Earth, files output from kmlwrite can be seen immediately in Google Earth, if that application is available to the user. If the files are uploaded to a publicly accessible Web server, they can be viewed by anyone on the Internet via Google Maps or other Web sites and browser utilities that can read and display KML files. Google Maps and Google Maps for mobile do not support the range of KML markup that Google Earth supports (for example, placemark locations must be specified to them as coordinates, not as addresses). See the Google KML documentation at http://code.google.com/apis/kml/documentation/mapsSupport.html for more information.
kmlwrite accepts latitude and longitude point vectors, passed either in geostructs or as column arrays. It also accepts addresses, which can be as general as a country's name or as specific as a street address. When geostructs are the input, the attribute data in the geostruct can be formatted as HTML tables and included in the KML output. When latitude-longitude arrays are input, you can pass attributes to kmlwrite with strings. When addresses are the input, geostructs are not used.
To customize placemarks, you can control formatting of geostruct attributes in the KML file with an attribute specification, a struct used to format them (for example, to add units to length attributes or to control the number of decimal places for numeric values). A new support function, makeattribspec lets you change the names used as labels in placemarks (geostruct field names are used by default), omit fields from placemarks, and add HTML markup to the attributes displayed in placemark tables.
See Exporting Vector Geodata in the Mapping Toolbox User's Guide and the mapexkmlexport demo, "Exporting Vector Point Data to KML" for more information.
Improved Conversion Between Angle Units
The angledim function has been replaced by four, more specific, functions: fromRadians, fromDegrees, toRadians, and toDegrees (described below in Four New Angle-Unit Conversion Functions). However, angledim has been retained in Version 2.6 for backward compatibility. The functions degtorad, radtodeg, and unitsratio provide additional alternatives.
Because it must resolve both the input and output units, angledim is excessive for most applications. It works only for class double and it quietly discards the imaginary part of any complex input. You can use any of several more efficient alternatives:
If you are working from the command line, you can often replace angledim with degtorad or radtodeg. If you are converting angle units within a script or function and you know both the from and to unit names at the time of coding, then you can also replace angledim with degtorad or radtodeg. If you know either from or to at the time of coding, then you can use fromRadians, fromDegrees, toRadians, or toDegrees. Apply one of the following transformations to your code:
- angledim(angleIn,'radians',to) ⇒ fromRadians(to,angleIin)
- angledim(angleIn,'degrees',to) ⇒ fromDegrees(to,angleIin)
- angledim(angleIn,from,'radians') ⇒ toRadians(from,angleIn)
- angledim(angleIn,from,'degrees') ⇒ toDegrees(from,angleIn)
Also note that the functions in the fromRadians family can convert multiple variables in a single function call. For example, you can replace this code
angle1 = angledim(angle1InRadians,'radians',to);
angle2 = angledim(angle2InRadians,'radians',to);
with
[angle1,angle2] = fromRadians(to,angle1InRadians,angle2InRadians);
If you do not know either from or to at the time of coding, then you can call unitsratio to obtain the correct conversion factor, then multiply the values of one or more variables. For example, you can replace:
angle1Out = angledim(angle1In, from, to);
angle2Out = angledim(angle2In, from, to);
with
r = unitsratio(to, from);
angle1Out = r * angle1In;
angle2Out = r * angle2In;
Four New Angle-Unit Conversion Functions
The following functions have been added for efficient conversion of angle units (degrees or radians) when either the target or destination units (but not both) are unknown before run time.
- toDegrees — Convert angles to degrees
- toRadians — Convert angles to radians
- fromDegrees — Convert angles from degrees
- fromRadians — Convert angles from radians
If the output units match the inputs units, as in toDegrees(units, angle1, angle2,...), where units turns out to equal 'degrees', then the input angles are simply copied to the output angles.
Use these functions in place of angledim. The new functions are more efficient, especially when the value of either the from or to argument of angledim is known in advance and the value of the other angle-unit argument is not.
Improvements in Handling Length Units
Alternatives to the distdim Function
There are now more efficient ways to convert length and distance units than the distdim function. In place of distdim, you can use unitsratio to compute multiplicative factors to apply when converting between different units of distances and angles, which you can use in subsequent calculations. For other alternatives, see Replacing distdim in the distdim reference page for details.
The unitstr function Is Obsolete
The unitstr function, which validates names and abbreviations for units of distance, angle, and time, is obsolete and will be removed in a future release. The syntax str = unitstr(str,'times') has already been removed. Instead, see the documentation for unitsratio for a list of valid unit strings.
Compatibility Considerations. There is no replacement for unitstr, but unitsratio recognizes all the unit strings known to the toolbox.
Interpretation of "Miles" Units has Changed
As of R2007b, the following functions interpret distance units specified as 'miles' as International Miles, not Statute Miles:
- almanac
- daspectm
- elevation
- mapprofile
- paperscale
- scaleruler
Compatibility Considerations. This will not materially affect the accuracy of results in most cases; the lengths of the two types of miles only differ by about two parts per million (three millimeters). The distdim function's interpretation of miles has not changed. However, there are better alternatives to it; see the release note Alternatives to the distdim Function.
Four new low-level functions have been added that force longitudes, azimuths, or phase angles to span intervals of [0 360] or [-180 180] degrees or [0 2*pi] or [-pi pi] radians.
- wrapTo180 — Wrap angle in degrees to [-180 180]
- wrapTo360 — Wrap angle in degrees to [0 360]
- wrapToPi — Wrap angle in radians to [-pi pi]
- wrapTo2Pi — Wrap angle in radians to [0 2*pi]
The first two functions work in degrees, the next two in radians. None of them perform argument checking.
You can use the new wrapping and functions in place of npi2pi and zero22pi for greater efficiency. The older functions will eventually be removed from the toolbox.
New Function to Unwrap Sequences of Angles
The new unwrapMultipart function unwraps vectors of angles similarly to the MATLAB function unwrap, except that it handles vectors that include NaN separators, unwrapping each section separately. Use it to remove discontinuities from vectors of longitudes, azimuths, or phase angles that contain NaN-delimited sequences and as a replacement for the obsolete function smoothlong.
Improvements to Data Trimming in patchm and patchesm
The patchm and patchesm functions now completely trim away polygons and parts of polygons that fall outside your current map limits. This improvement also affects fillm, which calls patchm. Previously the patch functions simply shifted coordinates inward so that vertices collected at the edge of the limits, where they would appear as lines along map borders, unless obscured by the map frame. This change allows OpenGL to better render the patch objects constructed by patchm and patchesm, making them more compatible with the use of AlphaData to achieve transparency. See the release note Map Axes Now Display Transparent Objects More Easily for more details.
The more complete trimming in patchm and patchesm means that there are circumstances under which automatic reprojection can no longer display all the data provided to these functions. Automatic reprojection causes map objects created with plotm, linem, patchm, patchesm, and certain other display functions (but not geoshow) to be removed, projected, and redisplayed whenever a call to setm changes certain map axes properties, including the map limits and projection type. In the case of patchm, a set of polygons will become unavailable for automatic reprojection if all of the polygons are trimmed away completely. In the case of patchesm, which constructs a separate object for each polygon, any polygon that is trimmed away completely will be unavailable for reprojection, even if it would lie within newly defined map limits. In either of these cases, you should delete the handle(s) returned by patchm or patchesm, then repeat the original calls after changing your map axes properties.
Other potential compatibility issues:
- patchm and patchesm exhibit greater sensitivity to incomplete or incorrect polygon topology.
- You might need to manually set the renderer for proper display of some patch data
See the release note Map Axes Now Display Transparent Objects More Easily for information about rendering and the Mapping Toolbox demo mapexgshhs for an example of a situation where polygon topology necessitates manual setting of the renderer.
Higher Quality boston.tif GeoTIFF Satellite Image
The original boston.tif GeoTIFF satellite image has been replaced by a higher resolution image, created by and provided courtesy of GeoEye™. The new image has the same name as the old one, boston.tif. The new boston.tif file, and an overview image in JPEG format, boston_ovr.jpg, include material copyright © by GeoEye, all rights reserved. The new image is 2881-by-4481 pixels, with a ground pixel size of 3.2808333333 U.S. survey feet (one meter). The original image was 720-by-1120 pixels and had a ground pixel size of four meters. Both images cover the downtown section of Boston, Massachusetts, the Charles River, and parts of Cambridge. The new image is a "pan-sharpened" multispectral image with visible red, green, and blue bands, and is stored in RGB form. The original image was also multispectral, but was a simple composite of red, green, and blue bands, and it was written to the GeoTIFF file as an indexed-color image. One additional change is that rather using meters, the new image is spatially referenced to the Massachusetts State Plane Mainland coordinate system with units of U.S. survey feet. The overview image, boston_ovr.jpg, is referenced to latitude-longitude, with a ground pixel size of approximately 16 meters. For further information, refer to the text files boston.txt, boston_ovr.txt, and boston_metadata.txt in toolbox/map/mapdemos.
Older satellite images of Boston and a demo have been removed from Mapping Toolbox directories. The new boston.tif and boston_ovr.jpg images replace the images having the same names previously included in toolbox/map/mapdemos. In addition, several older images related to boston.tif have been removed:
- boston_red.tif
- boston_green.tif
- boston_blue.tif
- boston_pan.tif
- boston_enhanced_pan.tif
The mapexenhance demo ("Enhancing Multispectral GeoTIFF Images"), which used several of these images, has also been removed.
Map Axes Now Display Transparent Objects More Easily
It is now much easier to achieve transparency effects from the toolbox by setting the AlphaData property of an object. Previously, functions axesm, lightm, contourm, and contour3m set the figure's Renderer property: axesm and lightm set it to 'zbuffer', while contourm and contour3m set it to 'painters'. You then had to manually reset Renderer to 'opengl' in order for transparency to take effect.
Now the RendererMode of the figure retains the default MATLAB value of 'auto', causing MATLAB to select the most appropriate renderer for you; it will use OpenGL when appropriate, given your AlphaData settings. Using OpenGL not only enables transparency effects, it also can make use of hardware graphics acceleration capabilities should they be available.
If you need a particular map display to look the same as it did in Mapping Toolbox Version 2.5 (R2007a), in most cases you can just issue the command
set(gcf,'Renderer','zbuffer')
after you construct your map axes. If you are calling contourm or contour3m, issue the command
set(gcf,'Renderer','painters')
after you call the contouring function.
The consequence of doing this is that you will not be able to use transparency with that map figure until you reset its renderer to 'opengl' or set its 'RendererMode' back to 'auto', which is its default state.
The arcgridread Function Now Imports Noninteger Data Grids
In previous releases of the toolbox, arcgridread could only import data grids that had integer values (often of meters or feet). This limitation has now been removed, such that input grids can contain arbitrary values in decimal notation.
Change to avhrrlambert Function Behavior When No Data Is Available
In previous releases of the toolbox, avhrrlambert would error if the quadrangle defined by latlim and lonlim (when projected to form a polygon in the appropriate Lambert Equal Area Azimuthal projection) failed to intersect the bounding box of the data in the projected coordinates. In this release, avhrrlambert does not error when this occurs but returns empty matrices.
If you depend on avhrrlambert to error when there is no data in your quadrangle, you will need to change your code.
Enhancements to Mapping Toolbox User's Guide
Several sections of the chapter Understanding Geospatial Geometry have been rewritten and new material has been added to better explain critical topics such as ellipsoid models, units of and notations for angles and length, and the conversions that are possible between various units. There is also a new section, Exporting Vector Geodata, explaining and illustrating how to use the new kmlwrite and makeattribspec functions.
Functions deg2rad and rad2deg No Longer Convert Complex to Real
In prior versions, when given complex inputs, functions deg2rad and rad2deg issued a warning and then converted their inputs to real. Now they no longer do either of these things; in the unlikely event of complex input, these functions simply scale the imaginary part by the same factor as the real part. For example, in R2007a and earlier releases, they behave as follows:
>> deg2rad(180i)
Warning: Imaginary parts of complex ANGLE argument ignored
> In deg2rad at 16
ans =
0
Going forward from this release, the result is
>> deg2rad(180i)
ans =
0 + 3.1416i
Degrees-Minutes-Seconds Conversion Functions Are Obsolete and Error if Used
The following functions, which accepted or produced double scalars to represent degrees, minutes, and seconds now error when used, and will be removed completely from the toolbox in a future release:
- deg2dm
- deg2dms
- dms2deg
- dms2dm
- dms2mat
- dms2rad
- mat2dms
- rad2dm
- rad2dms
The scalar DM and DMS encodings are being eliminated from the toolbox because they were never used for internal computations, and always had the potential to generate serious numerical errors if passed accidentally to functions that expected normal latitude-longitude tuples. They also made the functions that accepted them less efficient due to the need to convert from DM or DMS to fractional latitudes and longitudes before processing the input data.
In every case, an alternative that does not use the old degrees-minutes-seconds scalar encoding exists. See the following section on compatibility for replacements and New Functions for Degrees-Minutes-Seconds Conversions in the V2.5 Release Notes for descriptions of replacement functions, and the compatibility considerations below for descriptions of alternative syntaxes and expressions you can use for degrees-minutes-seconds conversions.
DM and DMS representations are widely used in published reports and can occur in geodata that you want to read into the MATLAB workspace. You can still import and export DM and DMS data, but Mapping Toolbox functions no longer accepts the old encodings as alternatives to floating-point representations of latitude and longitude for internal manipulations.
The following functions (which all use scalar DMS encoding) are being retired. They remain in the product for R2007b, but now generate errors when used. They will be removed completely in the next version. Use the alternative suggested in lieu of these functions.
- deg2dm — Instead use degrees2dm to convert degrees to degrees-minutes vector.
- deg2dms — Instead use degrees2dms to convert degrees to degrees-minutes-seconds vector.
- dms2deg — Instead use dms2degrees to convert degrees-minutes-seconds vector to degrees.
- dms2dm — Instead combine dms2degrees and degrees2dm, as in degrees2dm(dms2degrees([-29 42 18.7])) to remove the seconds component from a degree-minutes-second vector.
- dms2mat — Instead use degrees2dms to convert degrees to degrees-minutes-seconds vector.
- dms2rad — Instead use dms2degrees to convert degrees-minutes-seconds vector to degrees and call degtorad or multiply by pi/180.
- mat2dms — Instead use dms2degrees to convert degrees-minutes-seconds vector to degrees.
- rad2dm — Instead, call radtodeg or multiply input arguments by 180/pi, and then call degrees2dm.
- rad2dms — Instead, call radtodeg or multiply input arguments by 180/pi, and then call degrees2dms.
In addition, the axesm and setm functions no longer accept the strings 'dms' and 'dm' for setting either the AngleUnits or LabelUnits properties of a map axes.
Many other Mapping Toolbox functions optionally accept angle strings for their units parameter; the following 57 functions now only accept 'degrees' and 'radians', whereas in prior versions they would also accept 'dm' and 'dms' as values for units:
angl2str | distance | histr | putpole | stdist |
angledim | eastof | imbedm | rcurve | stdm |
antipode | elevation | interpm | reckon | timezone |
areaint | ellipse1 | intrplat | rhxrh | track |
areamat | epsm | intrplon | rotatem | track1 |
areaquad | eqa2grn | mapprofile | rsphere | track2 |
axesm | gc2sc | meanm | scaleruler | unitstr |
azimuth | gcxgc | meshgrat | scircle1 | westof |
convertlat | gcxsc | neworig | scircle2 | zero22pi |
crossfix | gradientm | newpole | scxsc |
|
daspectm | grn2eqa | npi2pi | setm |
|
departure | hista | org2pol | smoothlong |
|
These functions now error when provided 'dm' or 'dms' for their units argument.
Time Conversion Functions Are Obsolete and Error if Used
The following functions, which converted time representations, now error when used and will be removed completely from the toolbox in a future release:
- hms2hm
- hms2hr
- hms2mat
- hms2sec
- hr2hm
- hr2hms
- hr2sec
- mat2hms
- sec2hm
- sec2hms
- sec2hr
- time2str
- timedim
These functions now raise errors when they are invoked. They will be completely removed in a future version of the toolbox. No substitutes have been provided, as no operations of the toolbox have ever depended on them.
The cmapui GUI now errors if you attempt to use it. It will be completely removed from the next Mapping Toolbox version. Use the MATLAB colormapeditor GUI instead, which provides better functionality. You can also use the Colormap drop-down menu in the Property Editor (part of the MATLAB plotting tools and available via the propedit command) to select a built-in colormap; the custom option on that drop-down menu opens colormapeditor. To set up a colormap for terrain displays, you can use the demcmap function. To generate an appropriate (but random) colormap for political maps, use the polcmap function.
Functions tigermif and tigerp Are Obsolete and Error if Used
The following functions error and issue an error message when you attempt to use them:
- tigerp — Read TIGER p and pa thinned boundary files (ArcInfo format)
- tigermif — Read the TIGER MIF thinned boundary file (MapInfo format)
In place of these format readers, download U.S. Census cartographic boundary files in shapefile format and use shaperead to import them.