Maps

2.4 Maps

A map can consist of a combination of elements and attributes.

These elements and attributres can include the following:

Background image
Title
Legend
Query window
Footnote (such as for a copyright notice)
Base map
Predefined themes (in addition to any in the base map)
JDBC themes (with dynamic queries)
Dynamically defined (temporary) styles

These elements and attributes, when specified in a map request, define the content and appearance of the generated map. Map Visualization Servers contains detailed information about the available elements and attributes for a map request.

A map can have a base map and a stack of themes rendered on top of each other in a window. A map has an associated coordinate system that all themes in the map must share. For example, if the map coordinate system is 8307 (for Longitude / Latitude (WGS 84), the most common system used for GPS devices), all themes in the map must have geometries defined using that coordinate system.

You can add themes to a map by specifying a base map name or by using the programming interface to add themes. The order in which the themes are added determines the order in which they are rendered, with the last specified theme on top, so be sure you know which themes you want in the background and foreground.

All base map names and definitions for a database user are stored in that user's USER_SDO_MAPS view, which is described in Map Visualization Component Metadata Views and xxx_SDO_MAPS Views. The DEFINITION column in the USER_SDO_MAPS view contains an XML definition of a base map.

Example 2-49 shows a base map definition.

Example 2-49 XML Definition of a Base Map

<?xml version="1.0" ?>
<map_definition>
<theme name="theme_us_states"    min_scale="10"  max_scale="0"/>
<theme name="theme_us_parks"     min_scale="5"   max_scale="0"/>
<theme name="theme_us_highways"  min_scale="5"   max_scale="0"/>
<theme name="theme_us_streets"   min_scale="0.05" max_scale="0"/>
</map_definition>

Each theme in a base map can be associated with a visible scale range within which it is displayed. In Example 2-49, the theme named theme_us_streets is not displayed unless the map request is for a map scale of 0.05 or less and greater than 0 (in this case, a scale showing a great deal of detail). If the min_scale and max_scale attributes are not specified, the theme is displayed whenever the base map is displayed. (For more information about map scale, see Map Size and Scale.)

The display order of themes in a base map is the same as their order in the base map definition. In Example 2-49, the theme_us_states theme is rendered first, then theme_us_parks, then theme_us_highways, and finally (if the map scale is within all specified ranges) theme_us_streets.

Parent topic: Map Visualization Concepts

2.4.1 Map Size and Scale

Map size is the height of the map in units of the map data space. For example, if the map data is in WGS 84 geographic coordinates, the map center is (-120.5, 36.5), and the size is 2, then the height of the map is 2 decimal degrees, the lower Y (latitude) value is 35.5 degrees, and the upper Y value is 37.5 decimal degrees.

Map scale is expressed as units in the user's data space that are represented by 1 inch on the screen or device. Map scale for the map visualization component is actually the denominator value in a popular method of representing map scale as 1/n, where:

1, the numerator, is 1 unit (1 inch for the map visualization component) on the displayed map.
n, the denominator, is the number of units of measurement (for example, decimal degrees, meters, or miles) represented by 1 unit (1 inch for the map visualization component) on the displayed map.

For example:

If 1 inch on a computer display represents 0.5 decimal degree of user data, the fraction is 1/0.5. The decimal value of the fraction is 2.0, but the scale value for the map visualization component is 0.5.
If 1 inch on a computer display represents 2 miles of user data, the fraction is 1/2. The decimal value of the fraction is 0.5, but the scale value for the map visualization component is 2.
If 1 inch on a computer display represents 10 miles of user data, the fraction is 1/10. The decimal value of the fraction is 0.1, but the scale value for the map visualization component is 10.

The min_scale and max_scale attributes in a <theme> element describe the visible scale range of a theme. These attributes control whether or not a theme is displayed, depending on the current map scale. The default scale value for min_scale is positive infinity, and the default value for max_scale is negative infinity (or in other words, by default display the theme for all map scales, if possible given the display characteristics).

min_scale is the value to which the display must be zoomed in for the theme to be displayed. For example, if parks have a min_scale value of 5 and if the current map scale value is 5 or less but greater than the max_scale value, parks will be included in the display; however, if the display is zoomed out so that the map scale value is greater than 5, parks will not be included in the display.
max_scale is the value beyond which the display must be zoomed in for the theme not to be displayed. For example, if counties have a max_scale value of 3 and if the current map scale value is 3 or less, counties will not be included in the display; however, if the display is zoomed out so that the map scale value is greater than 3, counties will be included in the display.

A high min_scale value is associated with less map detail and a smaller scale in cartographic terms, while a high max_scale value is associated with greater map detail and a larger scale in cartographic terms. (Note that the map visualization component meaning of map scale is different from the popular meaning of cartographic map scale.) The min_scale value for a theme should be larger than the max_scale value. Example 2-49 in Maps includes min_scale and max_scale values.

You also assign scale values for theme labels, to enable the showing or hiding of labels with values different from the base theme scales, by using the theme label scale parameters label_min_scale and label_max_scale. These parameters are similar to the min_scale and max_scale parameters, but the labels are shown if the map scale is in the visible range defined by label_min_scale and label_max_scale. (The label scale values are ignored if the theme is not in the visible scale range defined by min_scale and max_scale.) The following is a theme definition with label scale values; the labels will be shown when the map scale is between 5 and 2, but the theme features will be shown when the map scale is between 10 and 0:

<theme name="theme_us_states" min_scale="10" max_scale="0" 
     label_min_scale="5" label_max_scale="2"/>

To determine the current map scale for a map returned by the map visualization component, first find the map size, namely the height (vertical span) of the map in terms of the coordinate system associated with the map data. For example, assume that a map with a height of 10 (miles, meters, decimal degrees, or whatever unit of measurement is associated with the data) is requested, and that the map is drawn on a device with a size of 500 by 350 pixels, where 350 is the height. The map visualization component assumes a typical screen resolution of 96 dpi. Because 96 pixels equals 1 inch, the height of the returned map is 3.646 inches (350/96 = 3.646). In this example, the size of the map is 10, and therefore the map scale is approximately 2.743 (10/3.646 = 2.743).

Alternatively, you can request a map using a map scale value without specifying a unit, such as 50000 for a scale of 1:50000, by specifying the scale_mode theme attribute value as ratio. (If the scale_mode theme attribute value is screen_inch, the scale refers to a unit.) To use a scale defined without a unit, request the map specifying the center and ratio scale.

To find the equivalent map visualization component screen inch scale for a ratio scale, follow these steps:

Find the numerical fraction of a meter associated with one screen pixel. For example, if the screen resolution is 96 dpi (dots per inch), the number of meters on the screen for each screen pixel is 0.000265 (that is, 0.0254/96).
Find the map scale for one screen pixel (the mapdotScale value), as follows:
- For projected data (meters), multiply the result of step 1 by the ratio scale. For example, if the ratio scale is 50000 (50 thousand) and the screen resolution is 96 dpi, the result is 13.25 meters for each pixel (50000 * 0.000265).
- For geodetic data (degrees), multiply the result of step 1 by the number of meters (on the surface of the Earth) for each degree. (This number will depend on the coordinate system associated with the data.) For example, if one degree = 111195 meters and if the screen resolution is 96 dpi, the result is 29.466675 meters for each pixel (111195 * 0.000265).
- For data using any other unit, use the approach for projected data using meters.
Because the map visualization component scale is per screen inch instead of per screen pixel, multiply the result of step 2 by the dpi value. For example, if the result of step 2 is 13.25 meters at 96 dpi, the number of meters for each screen inch is 1272 (13.25 * 96).

Parent topic: Maps

2.4.2 Map Legend

A map legend is an inset illustration drawn on top of the map and describing what various colors, symbols, lines, patterns, and so on represent. You have flexibility in specifying the content and appearance of the legend. You can:

Customize the background, border style, and font
Have one or more columns in the legend
Add space to separate legend entries
Indent legend entries
Use any map visualization component style, including advanced styles

Example 2-50 is an excerpt from a request that includes a legend.

Figure 2-14 Map with Legend

Description of "Figure 2-14 Map with Legend"

Notes on Example 2-50 and Figure 2-14:

This example shows a legend with a single column, although you can create multiple columns in a legend.
Each entry in the column definition can identify label text and whether the text is the legend title (is_title="true"), a style name and associated text, or a separator (is_separator="true") for vertical blank space to be added (after the cities entry in this example).

As an alternative to specifying the legend content in one or more <column> elements, you can request an automatic legend based on the map request. With an automatic legend, you specify the legend header, and the map visualization component generates the legend based on the themes that have any interaction with the map area. Themes from the map request and from the base map are considered. (Some legend items might not be visible, though, such as if a theme interacts with the query window but no features of the theme are visible on the map.)

Example 2-51 is a map request that requests an automatic legend (because the <legend> element does not include any <column> elements).

Example 2-52 requests an automatic legend in which the <legend> elements specifies the themes to be used to generate the legend items. In this example, even if the map result shows more themes, the legend items are based on the THEME_COUNTIES_3397829 and THEME_US_AIRPORT themes specified in the <legend> element.

You cannot combine an automatic legend with the use of <column> elements. If the <legend> element contains any <column> elements, a column/entry legend is created.

The map visualization component uses the following considerations when it builds automatic legend items:

Each legend column has a maximum of five entries (an advanced style is considered one entry).
The legend text for simple rendering styles comes from the theme description if defined, otherwise from the theme name.
If a rendering style is used in more than one theme, the style is repeated in the legend but with text related to the theme to which it applies.
Labeling styles are not repeated in the legend. The style text for labeling styles comes from the style description.
Advanced styles are not repeated in the legend.

If you also specify a map title, note, or logo (or any combination), be sure that the legend and the other features have different positions. (Map titles, notes, and logos are explained in Specifying Global Map Configuration Options.) The default position for a legend is SOUTH_WEST.

Example 2-50 Legend Included in a Map Request

<?xml version="1.0" standalone="yes"?>
<map_request
             basemap="density_map"
             datasource = "mvdemo"
             width="640"
             height="480"
             bgcolor="#a6cae0"
             antialiase="false"
             format="PNG_STREAM">
  <center size="4.2">
     <geoFeature render_style="m.image134_bw">
         <geometricProperty typeName="center">
             <Point srsName="SDO:8307">
                 <coordinates>-121.2615, 37.5266</coordinates>
             </Point>
         </geometricProperty>
     </geoFeature>
  </center>
 
  <legend bgstyle="fill:#ffffff;fill-opacity:100;stroke:#a3a3a3" profile="MEDIUM" position="SOUTH_WEST">
          <column>
            <entry text="Legend" is_title="true" />
            <entry style="M.IMAGE134_BW" text="Center" />
            <entry style="M.ALL_CITY_L2" text="Cities" />
            <entry is_separator="true" />
            <entry style="L.S04_ROAD_INTERSTATE" text="Interstates" />
            <entry text="County population:" />
            <entry style="V.COUNTY_POP_DENSITY_8" tab="1" />
          </column>
  </legend>
 
  <!--
  <themes>
 
  </themes>
  -->
 
</map_request>

Figure 2-14 shows a map with the legend specified in Example 2-50.

Example 2-51 Map Request with Automatic Legend

<?xml version="1.0" standalone="yes"?>
<map_request
             title="Automatic legend"
             datasource = "mvdemo"
             width="640"
             height="480"
             bgcolor="#a6cae0"
             antialiase="false"
             format="PNG_STREAM">
  <center size="4.5">
     <geoFeature >
         <geometricProperty typeName="center">
             <Point>
                 <coordinates>-122.2615, 37.5266</coordinates>
             </Point>
         </geometricProperty>
     </geoFeature>
  </center>
 
  <themes>
    <theme name="THEME_COUNTIES_3397829" />
    <theme name="THEME_US_ROAD1" />
    <theme name="THEME_US_AIRPORT" />
  </themes>
 
 <legend bgstyle="fill:#ffffff;fill-opacity:128;stroke:#ff0000;stroke-opacity:128" profile="medium" font="Courier">
  </legend>
 
</map_request>

Example 2-52 Automatic Legend with Themes Specified

<map_request
             title="Legend with themes defined"
             datasource = "mvdemo"
             width="640"
             height="480"
             bgcolor="#a6cae0"
             antialiase="false"
             format="PNG_STREAM">
  <center size="4.5">
     <geoFeature >
         <geometricProperty typeName="center">
             <Point>
                 <coordinates>-122.2615, 37.5266</coordinates>
             </Point>
         </geometricProperty>
     </geoFeature>
  </center>
 
  <themes>
    <theme name="THEME_COUNTIES_3397829" />
    <theme name="THEME_US_ROAD1" />
    <theme name="THEME_US_AIRPORT" />
  </themes>
 
 <legend bgstyle="fill:#ffffff;fill-opacity:128;stroke:#ff0000;stroke-opacity:128" profile="medium" font="Courier">
  <themes>
    <theme name="THEME_COUNTIES_3397829" />
    <theme name="THEME_US_AIRPORT" />
  </themes>
 </legend>
 
</map_request>

Parent topic: Maps