2 OracleAS MapViewer Concepts

2.2.1 Specifying a Label Style for a Bucket

For collection-based bucket styles and individual range-based bucket styles (described in Section A.6.1.1 and Section A.6.1.2, respectively), you can specify a labeling style by using the label_style attribute in each bucket element. Example 2-1 creates an advanced style named V.RB1 in which each bucket is assigned a text label style (using the label_style attribute), with some styles being used for several buckets.

<?xml version="1.0" ?>
<AdvancedStyle>
  <BucketStyle>
     <Buckets>
      <RangedBucket seq="0"  label="10k or less"  high="10000" 
        style="c.rb13_1"  label_style="T.AIRPORT NAME"/>
      <RangedBucket seq="1"  label="10k - 20k" low="10000" high="20000" 
        style="c.rb13_2"  label_style="T.CITY NAME"/>
      <RangedBucket seq="2"  label="20k - 30k" low="20000" high="30000" 
        style="c.rb13_3"  label_style="T.CITY NAME"/>
      <RangedBucket seq="4"  label="30k - 40k" low="30000" high="40000" 
        style="c.rb13_4"  label_style="T.CITY NAME"/>
      <RangedBucket seq="5"  label="40k - 50k" low="40000" high="50000" 
        style="c.rb13_5"  label_style="T.CITY NAME"/>
      <RangedBucket seq="6"  label="50k - 75k" low="50000" high="75000" 
        style="c.rb13_6"  label_style="T.ROAD NAME"/>
      <RangedBucket seq="7"  label="75k - 100k" low="75000" high="100000" 
        style="c.rb13_7"  label_style="T.PARK NAME"/>
      <RangedBucket seq="8"  label="100k - 125k" low="100000" high="125000" 
        style="c.rb13_8"  label_style="T.RED STREET"/>
      <RangedBucket seq="9"  label="125k - 250k" low="125000" high="250000" 
        style="c.rb13_9"  label_style="T.ROAD NAME"/>
      <RangedBucket seq="10"  label="250k - 450k" low="250000" high="450000" 
        style="c.rb13_10"  label_style="T.ROAD NAME"/>
      <RangedBucket seq="11"  label="450k - 650k" low="450000" high="650000" 
        style="c.rb13_11"  label_style="T.ROAD NAME"/>
      <RangedBucket seq="12"  label="650k up"   low="650000" style="c.rb13_13"/>
      </Buckets>
  </BucketStyle>
</AdvancedStyle>

For individual range-based buckets, the lower-bound value is inclusive, while the upper-bound value is exclusive (except for the range that has values greater than any value in the other ranges; its upper-bound value is inclusive). No range is allowed to have a range of values that overlaps values in other ranges.

If the V.RB1 style in Example 2-1 is used in a map request, it displays a map that might look like the display in Figure 2-1, where the county names are shown with labels that reflect various text styles (in this case depending on the county's total population).

Figure 2-1 Varying Label Styles for Different Buckets

Description of "Figure 2-1 Varying Label Styles for Different Buckets"

In Example 2-1, all buckets except the last one specify a label style. For any features that fall into a bucket that has no specified label style, the label style (if any) applied to the feature depends on the following:

• If the <label> element of the theme's styling rules specifies a label style other than the advanced style itself, the specified label style is used to label the feature. In the following example, because the <label> element's style specification (T.STATE_NAME) is different from the <features> element's style specification (V.RB1), features that fall into a bucket with no specified label style are labeled using the T.STATE_NAME style:

  <?xml version="1.0" standalone="yes"?>
  <styling_rules>
    <rule column="TOTPOP">
      <features style="V.RB1">
      </features>
      <label column="county" style="T.STATE NAME">
          1
      </label>
    </rule>
  </styling_rules>
  
  

• If the <label> element of the theme's styling rules specifies the advanced style as its label style, the feature is not labeled. (This is why some counties in Figure 2-1 are not labeled.) In the following example, because the <features> and <label> elements both specify the advanced style V.RB1, features that fall into a bucket with no specified label style are not labeled:

  <?xml version="1.0" standalone="yes"?>
  <styling_rules>
    <rule column="TOTPOP">
      <features style="V.RB1">
      </features>
      <label column="county" style="V.RB1">
          1
      </label>
    </rule>
  </styling_rules>
  

2.2.2 Orienting Text Labels and Markers

You can control the orientation of text labels and markers on a map by using oriented points. The oriented point is a special type of point geometry introduced in Oracle Spatial for Oracle Database 10g Release 1 (10.1). In an oriented point, the coordinates represent both the location of the point and a virtual end point, to indicate an orientation vector. The text is aligned or the marker symbol is rotated according to the orientation vector, which is explained in Section 3.2.5 and illustrated in Figure 3-3 in that section. For more information about oriented points, see Oracle Spatial User's Guide and Reference.

2.2.2.1 Controlling Text Style Orientation

To orient the text label of a point in the direction of an orientation vector, you can specify the point as an Oracle Spatial oriented point in the map request. When OracleAS MapViewer labels an oriented point, it automatically centers the text label on the point position, and aligns the label so that it points in the direction of the orientation vector.

For each feature to be so labeled, you must specify its location as an oriented point. You can group these oriented points in a single table and create a spatial index on the column containing the point geometries. You can then create a theme based on the table, specifying a desired text style as the labeling, and specifying transparent color style as the rendering style so that the points themselves are not displayed on the map.

Example 2-2 is a map request that labels a single oriented point with coordinates (12,14, 0.3,0.2), where (12,14) represents the X and Y coordinates of the point and (0.3,0.2) represents the orientation vector. It renders the point using a dynamically defined transparent color style (named transparent_color) to ensure that the text is displayed but the underlying point is not displayed.

Example 2-2 Labeling an Oriented Point

<map_request
  title="Labeling Oriented Points"
  datasource="my_datasource"   width="400"  height="300"
  antialiase="true"
  format="PNG_STREAM">
 
  <themes>
    <theme name="theme1">
       <jdbc_query
         spatial_column="geom"  jdbc_srid="8265"
         render_style="transparent_color" 
         label_column="label" label_style="t.street name"
         datasource="tilsmenv">
         SELECT MDSYS.SDO_GEOMETRY(2001, 8265, NULL, 
                      MDSYS.SDO_ELEM_INFO_ARRAY(1, 1, 1, 3, 1, 0), 
                      MDSYS.SDO_ORDINATE_ARRAY(12, 14, .3, .2))
         geom, 'Oriented Point' label FROM dual
       </jdbc_query>
     </theme>
  </themes>
 
  <styles>
    <style name="transparent_color">
      <svg width="1in" height="1in">
        <g class="color" style="stroke:#ff0000;stroke-opacity:0">
          <rect width="50" height="50"/>
        </g>
      </svg>
    </style>
  </styles>
</map_request>

Figure 2-2 shows part of the map generated by the request in Example 2-2. (The label is the phrase Oriented Point.)

Figure 2-2 Map Display of the Label for an Oriented Point

Description of "Figure 2-2 Map Display of the Label for an Oriented Point"

2.2.2.2 Controlling Marker Orientation

When a marker style is applied to an oriented point, OracleAS MapViewer automatically rotates the marker style so that it points to the orientation vector. Any necessary rotation of the marker style is around the center of the marker.

Figure 2-3 shows how you can use an oriented point to control the orientation of marker styles. In this figure, the original marker style is first shown without any rotation. However, when the marker is applied to the same oriented point shown in Example 2-2 in Section 2.2.2.1, the marker style is rotated accordingly (in this case about 34 degrees counterclockwise) to reflect the orientation vector.

Figure 2-3 Oriented Marker

Description of "Figure 2-3 Oriented Marker"

2.3.1 Predefined Themes

A predefined theme is a theme whose definition is stored in a user's database schema. All predefined themes for a database user are stored in that user's USER_SDO_THEMES view (described in Section 2.8, especially Section 2.8.2). When you specify a predefined theme in a map request, you need to specify only the theme name. OracleAS MapViewer automatically finds the theme's definition, constructs a query based on it, retrieves the relevant spatial and attribute data, and renders the theme according to the styling rules for the theme.

Each predefined theme must have an associated base table or view. If you base a theme on a view, you must insert a row in the view owner's USER_SDO_GEOM_METADATA view (described in Oracle Spatial User's Guide and Reference) specifying the view and its spatial column. If the view is a join view (that is, if it is based on multiple tables), you must specify the key_column attribute (described in Section A.7) in the theme's styling rules. The reason for this requirement is that OracleAS MapViewer by default caches geometries for a predefined theme based on the rowid in the base table; however, for a join view there is no ROWID pseudocolumn, so you must specify a key column.

For many themes (but not for GeoRaster, network, or topology themes), you can use the graphical Map Definition Tool predefined themes of varying complexity. For information about the Map Definition Tool, see Chapter 7.

<?xml version="1.0" standalone="yes"?>
<styling_rules>
  <rule>
    <features style="c.black gray">
    runway_number &gt; 1
    </features>
    <label column="name" style="t.airport name">
      1
    </label>
  </rule>
  <rule>
    <features style="m.airplane">
    runway_number = 1
    </features>
  </rule>
</styling_rules>

2.3.2 JDBC Themes

A JDBC theme is a theme that is dynamically defined with a map request. JDBC themes are not stored permanently in the database, as is done with predefined themes.

For a JDBC theme, you must specify a valid SQL query that retrieves all the necessary spatial data (geometries or other types of data, such as image, GeoRaster, network, or topology). If attribute data is needed, such as for thematic mapping or spatial data analysis, the query must also select it. In other words, you must provide a correct and complete query for a JDBC theme. In addition to the query, you can also specify the rendering and labeling styles to be used for the theme.

For a JDBC theme based on spatial geometries, OracleAS MapViewer processed the columns specified in the query according to the following rules:

• The column of type SDO_GEOMETRY is treated as the spatial data column.

• Any column whose name or alias matches that specified in the JDBC theme's label_column attribute is treated as the labeling column, whose values are used as text for labels.

• Any other columns are treated as attribute data columns, which may or may not be used by OracleAS MapViewer. For example, if the rendering style is an advanced style, any attribute columns are processed by that style in the order in which they appear in the SELECT list in the query. Thus, if you are performing thematic mapping and using an advanced style, you must specify all attribute columns that are needed for the thematic mapping, in addition to the geometry column and optional labeling column. (A labeling column can also be an attribute column, in which case you do not need to specify that column in the SELECT list.)

Example 2-4 is a map request that includes a JDBC theme.

<?xml version="1.0" standalone="yes"?>
<map_request title="My MAP" datasource = "mvdemo">

  <themes>
    <theme name="jdbc_theme_1">
       <jdbc_query
            datasource="mvdemo"
            jdbc_srid="41052"
            spatial_column="geometry"
            render_style="C.RED">
          SELECT geometry from states where name='MA' 
       </jdbc_query>
     </theme>
  </themes>

</map_request> 

SELECT geometry FROM states WHERE name='MA';

<?xml version="1.0" standalone="yes"?>
 <styling_rules>
   <rule>
     <features style="L.POOR_ROADS" asis="true">
        select sdo_lrs.clip_geom_segment(geometry,start_measure,end_measure)
              geometry 
        from (select /*+ no_merge use_hash(a b) */
                a.street_id, name, start_measure, end_measure, geometry
             from (select /*+ no_merge */ a.street_id, name, geometry
                   from philly_roads a
                   where sdo_filter(geometry,sdo_geometry(2002,41124,null,
                    sdo_elem_info_array(1,2,1),
                                       sdo_ordinate_array(?,?,?,?)),
                                 'querytype=window')='TRUE') a,
                   philly_road_conditions b
             where condition='POOR' and a.street_id = b.street_id)
     </features>
   </rule>
 </styling_rules>

2.3.3 Thematic Mapping

Thematic mapping refers to the drawing of spatial features based on their attribute values. OracleAS MapViewer uses thematic mapping to create maps in which colors or symbols are applied to features to indicate their attributes. For example, a Counties theme can be drawn using colors with different hues that map directly to the population density of each county, or an Earthquakes theme can be plotted with filled circles whose sizes map to the scale or damage of each earthquake.

To achieve thematic mapping, you must first create an advanced style that is suitable for the type of thematic map, and then create a theme for the features specifying the advanced style as the rendering style. In the styling rules for the theme, you must also specify attribute columns in the table or view whose values will be used to determine exactly how a feature will be rendered thematically by the advanced style.

For example, assume that you wanted to display a map in which the color used for each region reflects the level of sales for a particular product. To do this, create an advanced style that defines a series of individual range-based buckets (see Section A.6.1.2), where each bucket contains a predefined range of sales values for a product, and each bucket has an associated rendering style. (Each region will be rendered using the style associated with the range in which that region's sales value falls.) Also specify the name of the column or columns that provide the attribute values to be checked against the ranges. In other words, the advanced style defines how to map regions based on their sales values, and the theme's styling rules tie together the advanced style and the attribute column containing the actual sales values.

Figure 2-4 shows the relationship between an advanced style and a theme, and how the style and the theme relate to the base table. In this figure, the advanced style named V.SALES defines the series of buckets. The predefined theme named SALES_BY_REGION specified the V.SALES style in its styling rules. The theme also identifies the SALES column in the REGIONS table as the column whose value is to be compared with the bucket ranges in the style. (Each bucket could be associated with a labeling style in addition to or instead of a rendering style, as explained in Section 2.2.1.)

Figure 2-4 Thematic Mapping: Advanced Style and Theme Relationship

Description of "Figure 2-4 Thematic Mapping: Advanced Style and Theme Relationship"

In addition to the individual range-based buckets shown in Figure 2-4, OracleAS MapViewer supports other bucket styles, as explained in Section A.6.1. You can also use more than one attribute column for thematic mapping, such as when drawing pie charts (explained in Section 3.1.9).

The rest of this section presents additional examples of thematic mapping.

Example 2-6 is the XML definition for an Earthquakes theme.

<?xml version="1.0" standalone="yes"?> 
<styling_rules theme_type="nature"> 
  <rule column="RICHTER_SCALE"> 
    <features style="v.earthquakes"> 
    </features> 
  </rule> 
</styling_rules>

<?xml version="1.0" ?> 
<AdvancedStyle> 
  <VariableMarkerStyle basemarker="m.circle" startsize="7" increment="4"> 
     <Buckets> 
          <RangedBucket seq="0"  label="less than 4"  high="4"/> 
          <RangedBucket seq="1"  label="4 - 5" low="4" high="5"/> 
          <RangedBucket seq="2"  label="5 - 6" low="5" high="6"/> 
          <RangedBucket seq="3"  label="6 - 7" low="6" high="7"/> 
          <RangedBucket seq="4"  label="7 and up" low="7"/> 
      </Buckets> 
  </VariableMarkerStyle> 
</AdvancedStyle> 

Example 2-7 used the <VariableMarkerStyle> tag. The following examples use the <ColorSchemeStyle> tag in creating thematic maps of census blocks in California. Example 2-8 illustrates the use of a graduated color scale for a thematic mapping of population density. Example 2-9 is a thematic mapping of average household income using a graduated color scale. Example 2-10 is also a thematic mapping of average household income, but it uses a specific color style for each income range rather a graduated scale.

# ca pop density usbg_hhinfo 
<?xml version="1.0" standalone="yes"?> 
<styling_rules theme_type="political"> 
<rule column="densitycy"> 
   <features style="v.CA Pop density"> 
   </features> 
 </rule> 
</styling_rules> 

<?xml version="1.0" ?> 
<AdvancedStyle> 
  <ColorSchemeStyle basecolor="#ffff00" strokecolor="#00aaaa"> 
     <Buckets low="0.0" high="20000.0" nbuckets="10"/> 
  </ColorSchemeStyle> 
</AdvancedStyle> 

<?xml version="1.0" standalone="yes"?> 
<!-- # ca hh income theme  table = usbg_hhinfo  --> 
<styling_rules> 
<rule column="avghhicy"> 
   <features style="v.ca income"> 
   </features> 
 </rule> 
</styling_rules> 

<?xml version="1.0" ?> 
<AdvancedStyle> 
  <ColorSchemeStyle basecolor="#ffff00" strokecolor="#00aaaa"> 
  <!-- # income range with a color gradient --> 
     <Buckets> 
          <RangedBucket seq="0" label="less than 10k"  high="10000"/> 
          <RangedBucket seq="1" label="10-15k" low="10000" high="15000"/> 
          <RangedBucket seq="2" label="15-20k" low="15000" high="20000"/> 
          <RangedBucket seq="3" label="20-25k" low="20000" high="25000"/> 
          <RangedBucket seq="4" label="25-35k" low="25000" high="35000"/> 
          <RangedBucket seq="5" label="35-50k" low="35000" high="50000"/> 
          <RangedBucket seq="6" label="50-75k" low="50000" high="75000"/> 
          <RangedBucket seq="7" label="75-100k" low="75000" high="100000"/> 
          <RangedBucket seq="8" label="100-125k" low="100000" high="125000"/>
          <RangedBucket seq="9" label="125-150k" low="125000" high="150000"/>
          <RangedBucket seq="10" label="150-250k" low="150000" high="250000"/>
          <RangedBucket seq="11" label="250-500k" low="250000" high="500000"/>
          <RangedBucket seq="12" label="500k and up"   low="500000"/>
      </Buckets> 
  </ColorSchemeStyle> 
</AdvancedStyle> 

<?xml version="1.0" standalone="yes"?> 
<!-- # ca hh income theme  table = usbg_hhinfo  --> 
<styling_rules> 
<rule column="avghhicy"> 
   <features style="v.ca income 2"> 
   </features> 
 </rule> 
</styling_rules> 

<?xml version="1.0" ?>
<AdvancedStyle>
 <BucketStyle>
  <Buckets>
   <!-- # income ranges with specific colors -->
   <RangedBucket seq="0" label="less than 10k"  high="10000" style="c.rb13_1"/>
   <RangedBucket seq="1" label="10-15k" low="10000" high="15000" style="c.rb13_2"/>
   <RangedBucket seq="2" label="15-20k" low="15000" high="20000" style="c.rb13_3"/>
   <RangedBucket seq="3" label="20-25k" low="20000" high="25000" style="c.rb13_4"/>
   <RangedBucket seq="4" label="25-35k" low="25000" high="35000" style="c.rb13_5"/>
   <RangedBucket seq="5" label="35-50k" low="35000" high="50000" style="c.rb13_6"/>
   <RangedBucket seq="6" label="50-75k" low="50000" high="75000" style="c.rb13_7"/>
   <RangedBucket seq="7" label="75-100k" low="75000" high="100000" style="c.rb13_8"/>
   <RangedBucket seq="8" label="100-125k" low="100000" high="125000" style="c.rb13_9"/>
   <RangedBucket seq="9" label="125-150k" low="125000" high="150000" style="c.rb13_10"/>
   <RangedBucket seq="10" label="150-250k" low="150000" high="250000" style="c.rb13_11"/>
   <RangedBucket seq="11" label="250-350k" low="250000" high="350000" style="c.rb13_12"/>
   <RangedBucket seq="12" label="350k and up"   low="350000" style="c.rb13_13"/>
  </Buckets>
 </BucketStyle>
</AdvancedStyle>

<?xml version="1.0" ?> 
<AdvancedStyle> 
<BucketStyle> 
 <Buckets> 
  <CollectionBucket seq="0" label="Shell" style="m.shell gasstation"> 
   Shell 
  </CollectionBucket> 
  <CollectionBucket seq="1" label="Esso" style="m.esso gasstation"> 
   Esso 
  </CollectionBucket> 
  <CollectionBucket seq="2" label="Texaco"  style="m.texaco gasstation"> 
   Texaco 
 </CollectionBucket> 
  <CollectionBucket seq="3" label="BP"  style="m.bp gasstation"> 
   BP 
  </CollectionBucket> 
  <CollectionBucket seq="4" label="Other"  style="m.generic gasstation"> 
   Avia,Benzinex,Q8,Total,Witte Pomp 
  </CollectionBucket> 
  <CollectionBucket seq="5" label="DEFAULT" style="m.default gasstation">
   #DEFAULT#
  </CollectionBucket>
  </Buckets>
</BucketStyle> 
</AdvancedStyle> 

• m.esso gasstation, m.texaco gasstation, and the other style names have a space between the words in their names.

• The names are not case-sensitive. Therefore, be sure not to use case as a way of differentiating names. For example, m.esso gasstation and M.ESSO GASSTATION are considered the same name.

• A default collection bucket can be specified by using #DEFAULT# as its value. This bucket is used for any column values (gas station names) that are not specified in the other buckets.

A theme (theme_gasstation) is then defined that specifies the column (MERK) in the table that contains company names. The styling rules of the theme are shown in Example 2-12.

<?xml version="1.0" standalone="yes"?> 
<styling_rules> 
  <rule column="merk"> 
    <features style="v.gasstations"> 
    </features> 
    <label column="merk" style="t.SansSerif red 10"> 
      1 
    </label> 
  </rule> 
</styling_rules> 

In this table, the GEOM column contains spatial geometries, and the MERK column contains company names (Shell, Esso, and so on).

The styling rules for the theme_gasstation theme specify that the marker (style v.gasstations) at a location specified by the content of the GEOM column is determined by the value of the MERK column for that row. The style v.gasstations (see Example 2-11) specifies that if the column value is Shell, use the style m.shell gasstation; if the column value is Esso, use the style m.esso gasstation; and so on, including if the column value is any one of Avia, Benzinex, Q8, Total, and Witte Pomp, use the style m.generic gasstation; and if the column value is none of the preceding, use the style m.default gasstation.

2.3.4 Attributes Affecting Theme Appearance

Some attributes of the <theme> element affect only the appearance of the map display, rather than determining the data to be associated with the theme. These appearance-related attributes control whether and how the theme is processed and rendered when a map is generated. Examples include the following attributes:

• min_scale and max_scale determine whether or not a theme is displayed at various map scales (levels of resolution). For example, if you are displaying a map of streets, there are certain map scales at which the streets would become too dense for a usable display, such as when viewing an entire state or province. In this case, you should create a theme for streets, and specify minimum and maximum scale values to ensure that individual streets affected by the theme are displayed when the scale is appropriate and otherwise are not displayed.

• labels_always_on determines whether or not labels for the theme will be displayed if they would overlap another label. By choosing appropriate labels_always_on values and choosing an appropriate order of themes to be processed within a map request, you can control how cluttered the labels might become and which labels have priority in getting displayed.

• fast_unpickle determines the unpickling (unstreaming) method to be used, which can involve a trade-off between performance and precision in the display.

• fixed_svglabel, visible_in_svg, selectable_in_svg, onclick, onmousemove, onmouseover, and onmouseout affect the appearance of SVG maps.

To specify any appearance-related attributes, use the <theme> element (described in Section 3.2.14) with the XML API or the JavaBean-based API (see especially Section 4.3).

2.3.5 Image Themes

An image theme is a special kind of OracleAS MapViewer theme useful for visualizing geographically referenced imagery (raster) data, such as from remote sensing and aerial photography.

You can define an image theme dynamically or permanently (as a predefined theme) in the database. You can use image themes with vector (nonimage) themes in a map. Figure 2-5 shows a map in which an image theme (showing an aerial photograph of part of the city of Boston) is overlaid with themes showing several kinds of roadways in the city.

Figure 2-5 Image Theme and Other Themes Showing Boston Roadways

Description of "Figure 2-5 Image Theme and Other Themes Showing Boston Roadways"

Before you can define an image theme, you must follow these rules in organizing your image data:

• Store image data in its original format (such as JPEG) in a BLOB column in a database table.

• Add a geometry (SDO_GEOMETRY) column to the same table, and store the minimum bounding rectangle (MBR) for each image in that column.

  Each geometry in the MBR column contains the geographic bounds for an image, not its size in the pixel space. For example, if an orthophoto image is 2000 by 2000 pixels in size, but covers a ground rectangle starting at the corner of (936000, 248000) and having a width and height of 8000 meters, the MBR for the geometry column should be populated with (936000, 248000, 944000, 256000).

• Insert an entry for the geometry column in the USER_SDO_GEOM_METADATA view.

• Create a spatial index on the geometry column.

To predefine an image theme, follow the guidelines in Section 2.3.5.1. To define a dynamic image theme in a map request, follow the guidelines for defining a JDBC theme, as explained in Section 2.3.2 and Section 3.2.9, but note the following additional considerations with dynamic image themes:

• You must provide the original image resolution information when defining an image theme.

• OracleAS MapViewer by default automatically scales the image data when generating a map with an image theme, so that it fits the current query window. To disable this automatic scaling, specify imagescaling="false" in the map request.

For any image theme definition, note the following considerations:

• You cannot use the Map Definition Tool to create an image theme. Instead, you must create an image theme and add it to the OracleAS MapViewer instance programmatically, or you must predefine the theme as explained in Section 2.3.5.1.

• OracleAS MapViewer supports only GIF and JPEG image formats. To enable OracleAS MapViewer to visualize data in any other image format, you must implement a custom image renderer using the oracle.sdovis.CustomImageRenderer interface in Java, and then register your implementation class in the mapViewerConfig.xml file (to tell OracleAS MapViewer which custom image renderer to use for image data in a specific format). For detailed information about implementing and registering a custom image renderer, see Appendix C.

For an example of a map request specifying an image theme, including an explanation of how OracleAS MapViewer processes the request, see Example 3-6 in Section 3.1.6.

INSERT INTO user_sdo_themes  VALUES (
   'IMAGE_LEVEL_2', 
   'Orthophotos at pyramid level 2', 
   'IMAGES',
   'IMAGE_MBR', 
   '<?xml version="1.0" standalone="yes"?>
    <styling_rules theme_type="image" image_column="image"
                   image_format="JPEG" image_resolution="2"
                   image_unit="M">
      <rule >
        <features style="C.RED"> plevel=2 </features>
      </rule>
    </styling_rules>' );

2.3.6 GeoRaster Themes

A GeoRaster theme is a special kind of OracleAS MapViewer theme useful for visualizing GeoRaster objects. GeoRaster is a feature of Oracle Spatial that lets you store, index, query, analyze, and deliver raster image and gridded data and its associated metadata. GeoRaster objects are defined using the SDO_GEORASTER data type. For detailed information about GeoRaster, see Oracle Spatial GeoRaster.

Before you can use OracleAS MapViewer with GeoRaster themes, you must ensure that the Java Advanced Imaging (JAI) library files (jai_core.jar and jai_codec.jar) are in the OracleAS MapViewer library path, as explained in Section 1.4. You must also perform the following actions with the GeoRaster data:

1. Georeference the GeoRaster data to establish the relationship between cell coordinates of the GeoRaster data and real-world ground coordinates (or some other local coordinates).

   If you are using Oracle Database Release 10.1, you must also set the spatial resolution values.

2. Generate or define the spatial extent (footprint) associated with the raster data.

3. Optionally, generate pyramid levels that represent the raster image or data at different sizes and degrees of resolution.

4. Insert a row into the USER_SDO_GEOM_METADATA view that specifies the name of the GeoRaster table and the SPATIALEXTENT attribute of the GeoRaster column (that is, the column of type SDO_GEORASTER). The following example inserts a row for a table named GEOR_TABLE with a GeoRaster column named GEOR_COLUMN:

   INSERT INTO USER_SDO_GEOM_METADATA VALUES
   ( 'geor_table',
     'geor_column.spatialextent',
     SDO_DIM_ARRAY(
       SDO_DIM_ELEMENT('X', 496602.844, 695562.844, 0.000005),
       SDO_DIM_ELEMENT('Y',8788409.499,8973749.499, 0.000005)
     ),
     82279   -- SRID
   );
   
   

5. Create a spatial index on the spatial extent of the GeoRaster table. The following example creates a spatial index named GEOR_IDX on the spatial extent of the table named GEOR_TABLE:

   CREATE INDEX geor_idx ON geor_table(geor_column.spatialextent)
     INDEXTYPE IS MDSYS.SPATIAL_INDEX;
   
   

Example 2-17 in Section 2.3.6.1 prepares GeoRaster data for use and stores a GeoRaster theme in the database.

OracleAS MapViewer supports two types of map requests with objects from a GeoRaster table:

• A request containing a SQL statement to select one or more GeoRaster objects

• A request specifying a single GeoRaster object by the combination of its raster data table name and its rasterID attribute value in the SDO_GEORASTER object. (The rasterID attribute value in the SDO_GEORASTER object is distinct from and unrelated to any primary key or ID column in the GeoRaster table.)

The following elements and attributes apply to the definition of a GeoRaster theme:

• <jdbc_georaster_query> element: Specifies that this is a dynamically defined GeoRaster theme. For a theme that uses a SQL statement to select one or more GeoRaster objects, this element contains the SQL query statement (without a terminating semicolon). The complete DTD for this element is included in the map request DTD in Section 3.2.

• georaster_table attribute: Specifies the name of the GeoRaster table.

• georaster_column attribute: Specifies the name of the column of type SDO_GEORASTER in the GeoRaster table.

• polygon_mask attribute (optional): Specifies a set of two-dimensional coordinates representing a polygon, to be used as a mask to make transparent the part of the GeoRaster image that is outside the polygon mask. The coordinates are defined as x1,y1,x2,y2, . . . . The mask coordinates must be in the data coordinate space.

• raster_bands attribute (optional): Specifies the band composition to be assigned to the red, green, and blue channels. If you specify only one value, the resulting image uses one band (gray levels for monochromatic images). If you specify two values, they are used for the red and green channels, and the default blue band stored in the GeoRaster metadata is used for the blue channel. If you do not specify this attribute, OracleAS MapViewer uses the default values stored in the GeoRaster metadata.

• raster_pyramid attribute (optional): Specifies the pyramid level (level of resolution). If you do not specify this attribute, OracleAS MapViewer calculates the best pyramid level for the current window query and device area.

• raster_id attribute (only if the definition does not include a SQL statement): Specifies the rasterID attribute value in the SDO_GEORASTER object definition of the single GeoRaster object for the map request.

• raster_table attribute (optional, and only if the definition does not include a SQL statement): Specifies the raster data table associated with the single GeoRaster object for the map request.

Example 2-14 defines a GeoRaster theme that contains a SQL statement that selects a single GeoRaster object. The theme assigns band 1 to the red channel, band 2 to the green channel, and band 3 to the blue channel. Because the raster_pyramid attribute is not specified, OracleAS MapViewer calculates the best pyramid level by using the spatial resolution values set during or after the georeferencing process. (Note that in Example 2-14, georid=1 in the WHERE clause refers to a column named GEORID in the GeoRaster table named PCI_IMAGE.)

<theme name="georaster_theme">
  <jdbc_georaster_query
    georaster_table="pci_image" 
    georaster_column="georaster"
    raster_bands="1,2,3"
    jdbc_srid="82301"
    datasource="mvdemo"
    asis="false"> SELECT georaster FROM pci_image WHERE georid =1
  </jdbc_georaster_query>
</theme>

Example 2-15 defines a GeoRaster theme that specifies the single GeoRaster object whose rasterID attribute value in the SDO_GEORASTER object is 1 (raster_id="1") and associated with the raster data table named RDT_PCI. The theme specifies 2 as the pyramid level.

<theme name="georaster_theme">
  <jdbc_georaster_query
    georaster_table="pci_image"
    georaster_column="georaster"
    raster_id="1"
    raster_table="rdt_pci"
    raster_pyramid="2"
    raster_bands="1,2,3"
    jdbc_srid="82301"
    datasource="mvdemo"
    asis="false">
  </jdbc_georaster_query>
</theme>

INSERT INTO user_sdo_themes  VALUES (
   'GEOR_BANDS_012', 
   'Band 0 for red, 1 for green, 2 for blue', 
   'GEOR_TABLE',
   'GEOR_COLUMN', 
   '<?xml version="1.0" standalone="yes"?>
    <styling_rules theme_type="georaster" raster_table="RDT_PCI"
                   raster_id="1" raster_bands="0,1,2">
    </styling_rules>' );

<styling_rules theme_type="georaster">
  <rule>
    <features> georid=1
    </features>
  </rule>
</styling_rules>

connect scott/tiger
 
SET ECHO ON
SET FEEDBACK 1
SET NUMWIDTH 10
SET LINESIZE 100
SET PAGESIZE 10000
SET SERVEROUTPUT ON SIZE 5000
SET LONG 20000
SET TIMING ON
call dbms_java.set_output(5000);
 
-------------------------------------------------------------------
-- Create a GeoRaster table (a table that has a 
-- column of SDO_GEORASTER object type).
-------------------------------------------------------------------
 
create table georaster_table
    (georid     number primary key, 
     type       varchar2(32), 
     georaster  sdo_georaster);
 
-------------------------------------------------------------------
-- Create the GeoRaster DML trigger on the GeoRaster table.
--
-- This is REQUIRED for all GeoRaster tables.
-- It is used to manage the GeoRaster sysdata table.
-------------------------------------------------------------------
 
call sdo_geor_utl.createDMLTrigger('georaster_table', 'georaster');
 
-------------------------------------------------------------------
-- Create a raster data table (RDT).
--
-- It is used to store cell data of GeoRaster objects.
-- This step is not a requirement. If the RDT table does not
-- exist, the GeoRaster procedures or functions will generate it
-- automatically whenever needed.
-- However, for huge GeoRaster objects, some tuning and setup on those
-- tables can improve the scalability and performance significantly.
-- In those cases, it is better for users to create the RDTs.
-- The primary key must be added to the RDT if you create it.
-------------------------------------------------------------------
 
create table rdt_geor of sdo_raster 
  (primary key (rasterId, pyramidLevel, bandBlockNumber,
                rowBlockNumber, columnBlockNumber))
  lob(rasterblock) store as (nocache nologging);
 
commit;
 
----------------
-- Import the image.
----------------
 
connect system/manager;
 
call dbms_java.grant_permission('MDSYS','SYS:java.io.FilePermission',
  'lbs/demo/images/l7_ms.tif', 'read' );
 
call dbms_java.grant_permission('SCOTT','SYS:java.io.FilePermission',
  'lbs/demo/images/l7_ms.tif', 'read' );
  
connect scott/tiger;
 
 declare 
  geor SDO_GEORASTER;
begin
  delete from georaster_table where georid = 1;
 insert into georaster_table 
    values( 1, 'TIFF', sdo_geor.init('rdt_geor', 1) );
 select georaster into geor 
    from georaster_table where georid = 1 for update;
  sdo_geor.importFrom(geor, '', 'TIFF', 'file',
    'lbs/demo/images/l7_ms.tif');
  update georaster_table set georaster = geor where georid = 1;
  commit;
end;/
 
connect system/manager;
 
call dbms_java.revoke_permission('MDSYS','SYS:java.io.FilePermission',
       'lbs/demo/images/l7_ms.tif', 'read' );
 
call dbms_java.revoke_permission('SCOTT','SYS:java.io.FilePermission',
       'lbs/demo/images/l7_ms.tif', 'read' );
       
connect scott/tiger;
 
--------------------------
-- Change the GeoRaster format (optional).
--------------------------
 
declare
  gr1 sdo_georaster;
begin
  --
  -- Using changeFormat with a GeoRaster object:
  --
 
  -- 1. Select the source GeoRaster object.
  select georaster into gr1 
    from georaster_table where georid = 1;
 
  -- 2. Make changes. (Interleaving is application-dependent. For TIFF images,
  --    the default interleaving is BSQ.)
  sdo_geor.changeFormat(gr1, 'blocksize=(512,512,3) interleaving=BIP');
 
  -- 3. Update the GeoRaster object in the GeoRaster table.
  update georaster_table set georaster = gr1 where georid = 1;
 
  commit;
end;/
 
---------------------------
-- Generate pyramid levels (strongly recommended, but optional).
---------------------------
 
declare
  gr sdo_georaster;
begin
 
  -- 1. Select the source GeoRaster object.
  select georaster into gr 
    from georaster_table where georid = 1 for update;
 
  -- 2. Generate pyramids.
  sdo_geor.generatePyramid(gr, 'resampling=NN');
 
  -- 3. Update the original GeoRaster object.
  update georaster_table set georaster = gr where georid = 1;
 
  commit;
end;/
 
-----------------------------
-- Georeference the GeoRaster object.
-----------------------------
 
DECLARE
  gr sdo_georaster;
BEGIN
  SELECT georaster INTO gr FROM georaster_table WHERE georid = 1 FOR UPDATE;
  sdo_geor.georeference(gr, 82216, 1,
                        sdo_number_array(30, 0, 410000.000000),
                        sdo_number_array(0, -30,3759000.000000));
  UPDATE georaster_table SET georaster = gr WHERE georid = 1;
  COMMIT;
END;/

-----------------------------
-- Set the spatial resolutions (required for 10gR1 only)
-----------------------------
-- If you are using Oracle Database Release 10.1, set spatial resolutions. (Not
-- required if you are using Release 10.2.) The spatial resolution values of 
-- (30, 30) are from the ESRI world file or from the georeferencing information; 
-- however, you may have to compute these values if they are not part of 
-- the original georeferencing metadata.
DECLARE
  gr sdo_georaster;
BEGIN
  SELECT georaster INTO gr FROM georaster_table WHERE georid = 1 FOR UPDATE;
  sdo_geor.setSpatialResolutions(gr, sdo_number_array(30, 30));
  UPDATE georaster_table SET georaster = gr WHERE georid = 1;
  COMMIT;
END;
/

------------------------
-- Update the spatial extent.
------------------------
 
DECLARE
  sptext sdo_geometry;
BEGIN
  SELECT sdo_geor.generateSpatialExtent(a.georaster) INTO sptext 
          FROM georaster_table a WHERE a.georid=1 FOR UPDATE;
  UPDATE georaster_table a SET a.georaster.spatialextent = sptext WHERE a.georid=1;
  COMMIT;
END;/
 
commit;
 
------------------------------------------------------------------
-- Create metadata information for the GeoRaster spatial extent column.
------------------------------------------------------------------
 
INSERT INTO USER_SDO_GEOM_METADATA 
  VALUES (
  'GEORASTER_TABLE',
  'georaster.spatialextent',
  SDO_DIM_ARRAY(
    SDO_DIM_ELEMENT('X', 410000.0, 470000.0, 0.000005),
    SDO_DIM_ELEMENT('Y', 3699000.0,3759000., 0.000005)
     ),
  82216   -- SRID
);
 
------------------------
-- Create a spatial index on the spatial extent.
------------------------
 
CREATE INDEX georaster_idx ON georaster_table(georaster.spatialextent) 
INDEXTYPE IS MDSYS.SPATIAL_INDEX;
 
--------------------------------------------------------
-- Create a predefined GeoRaster theme for OracleAS MapViewer.
--------------------------------------------------------
 
INSERT INTO user_sdo_themes  VALUES (
   'GEORASTER_TABLE', 
   'GeoTiff image', 
   'GEORASTER_TABLE',
   'GEORASTER', 
   '<?xml version="1.0" standalone="yes"?>
    <styling_rules theme_type="georaster" raster_table="RDT_GEOR"
                   raster_id="1" raster_bands="0,1,2">
    </styling_rules>' );
    
commit;

2.3.7 Network Themes

A network theme is a special kind of OracleAS MapViewer theme useful for visualizing networks defined using the Oracle Spatial network data model. A network consists of a set of nodes and links. A network can be directed or undirected, although links and paths typically have direction. A network can be organized into different levels of abstraction, called a network hierarchy. OracleAS MapViewer assumes that network spatial tables in a network use the same coordinate system, and that these tables are indexed and registered as described in Oracle Spatial Topology and Network Data Models.

Network node, link, and path tables store geometries of type SDO_GEOMETRY. You can create JDBC themes that use these geometries. In addition, you can define dynamic themes that consider aspects of the network, such as the direction of links for a directed network.

The following elements and attributes apply to the definition of a network theme:

• <jdbc_network_query> element: Specifies that this is a dynamically defined network theme. The complete DTD for this element is included in the map request DTD in Section 3.2.

• network_name attribute: Specifies the name of the network.

• network_level attribute (optional): Specifies the network hierarchy level to which this theme applies. (For a nonhierarchical network, specify 1, which is the default value.)

• link_style attribute (optional): Specifies the style name to be used for links.

• direction_style attribute (optional): Specifies the style name to be used for a link direction marker (for example, a directional arrow image).

• direction_position attribute (optional): Specifies the position of the direction marker relative to the link start, as a number between 0 and 1. For example, 0.85 indicates 85 percent of the way between the link start and end points.

• direction_markersize attribute (optional): Specifies the size (number of pixels) of the direction marker.

• link_labelstyle attribute (optional): Specifies the style name to be used for link labels in the column specified in the link_labelcolumn attribute.

• link_labelcolumn attribute (optional): Specifies the name of the column containing link labels to be rendered using the style specified in the link_labelstyle attribute.

• node_style attribute (optional): Specifies the style name to be used for nodes.

• node_markersize attribute (optional): Specifies the size (number of pixels) of the node marker.

• node_labelstyle attribute (optional): Specifies the style name to be used for node labels in the column specified in the node_labelcolumn attribute.

• node_labelcolumn attribute (optional): Specifies the name of the column containing node labels to be rendered using the style specified in the node_labelstyle attribute.

• path_ids attribute (optional): Specifies one or more path ID values of stored paths to be rendered. For more than one path, use commas to delimit the path ID values. For example, path_ids="1,3,4" specifies that the paths with path ID values 1, 3, and 4 are to be rendered.

• path_styles attribute (optional): Specifies one or more style names associated with the paths specified in the path_ids attribute. For example, path_styles="C.RED,C.GREEN,C.BLUE" specifies styles to be used to render the first, second, and third paths (respectively) specified in the path_ids attribute.

• path_labelstyle attribute (optional): Specifies the style name to be used for path labels in the column specified in the path_labelcolumn attribute.

• path_labelcolumn attribute (optional): Specifies the name of the column containing path labels to be rendered using the style specified in the path_labelstyle attribute.

Additional network theme attributes related to network analysis are described in Section 2.3.7.2.

A network theme can combine attributes for links, nodes, and paths, or any combination. In such cases, OracleAS MapViewer first renders the links, then the paths, and then the nodes.

Example 2-18 defines a network theme that specifies attributes for the display of links and nodes in the network named NYC_NET.

<theme name="net_theme" user_clickable="false">
  <jdbc_network_query
    network_name="NYC_NET"
    network_level="1"
    jdbc_srid="8307"
    datasource="mvdemo"
    link_style="C.RED"
    direction_style="M.IMAGE105_BW"
    direction_position="0.85"
    direction_markersize="8"
    node_style="M.STAR"
    node_markersize="5"
    asis="false">
  </jdbc_network_query>
</theme>

INSERT INTO user_sdo_themes  VALUES (
   'NYC_NET_1',
   'New York City network',
   'NYC_NET_LINK_TABLE',
   'GEOMETRY',
   '<?xml version="1.0" standalone="yes"?>
    <styling_rules
              theme_type="network"
              network_name="NYC_NET"
              network_level="1">
      <rule>
         <features>
           <link
              style="C.RED"
              direction_style="M.IMAGE105_BW"
              direction_position="0.85"
              direction_markersize="8">
           </link>
           <path
              ids="1,3"
              styles="C.BLUE,C.GREEN">
           </path>
           <node
              style="M.CIRCLE"
              markersize="5">
           </node>
         </features>
         <label>
           <link column="LINK_ID" style="T.STREET NAME"> 1 </link>
         </label>
      </rule>
    </styling_rules>' );

<theme name="shortest_path_theme" user_clickable="false">
  <jdbc_network_query
    network_name="BI_TEST"
    network_level="1"
    jdbc_srid="0"
    datasource="mvdemo"
    analysis_algorithm="DIJKSTRA"
    shortestpath_style="L.PH"
    shortestpath_startnode="20"
    shortestpath_endnode="101"
    shortestpath_startstyle="M.STAR"
    shortestpath_endstyle="M.CIRCLE"
    asis="false">
  </jdbc_network_query>
</theme>

<theme name="within_cost_theme" user_clickable="false">
  <jdbc_network_query
    network_name="BI_TEST"
    network_level="1"
    jdbc_srid="0"
    datasource="mvdemo"
    analysis_algorithm="WITHINCOST"
    withincost_startnode="20"
    withincost_style="L.PH"
    withincost_cost="1"
    withincost_startstyle="M.STAR"
    asis="false">
  </jdbc_network_query>
</theme>

2.3.8 Topology Themes

A topology theme is a special kind of OracleAS MapViewer theme useful for visualizing topologies defined using the Oracle Spatial topology data model. The topology data model lets you work with data about nodes, edges, and faces in a topology. The spatial representations of nodes, edges, and faces are spatial geometries of type SDO_GEOMETRY. For nodes and edges, the geometries are explicitly stored; for faces, the initial lines (exterior and interior) are stored, allowing the face geometry to be generated.

In addition to the spatial representation of nodes, edges, and faces, a topology can have features. A feature (also called a topology geometry) is a spatial representation of a real-world object. Each feature is defined as an object of type SDO_TOPO_GEOMETRY, which identifies the topology geometry type, topology geometry ID, topology geometry layer ID, and topology ID. For detailed information, see Oracle Spatial Topology and Network Data Models.

OracleAS MapViewer can render topology features. It can also render a theme in debug mode (explained later in this section) to show the nodes, edges, and faces of a topology. For each topology theme, OracleAS MapViewer uses the topology metadata information stored in the USER_SDO_TOPO_METADATA view.

The following elements and attributes apply to the definition of a topology theme:

• <jdbc_topology_query> element: Specifies that this is a dynamically defined topology theme. The element can specify a SQL query statement (without a terminating semicolon). The complete DTD for this element is included in the map request DTD in Section 3.2.

• topology_name attribute: Specifies the name of the topology.

• feature_table attribute: Specifies the name of the feature table.

• spatial_column attribute: Specifies the name of the spatial feature column of type SDO_TOPO_GEOMETRY.

• label_column attribute: Specifies the column in the feature table that contains the text label to be used with each feature.

• label_style attribute: Specifies the name of the text style to be used to render the labels in the label column.

• render_style attribute: Specifies the name of the style to be used to render the topology.

Example 2-22 defines a topology theme that specifies attributes for the display of features and labels from the LAND_PARCELS table in the CITY_DATA topology. The SQL statement specifies the spatial feature column and the label column, and it includes all rows in the feature table.

<theme name="topo_theme" user_clickable="false">
  <jdbc_topology_query
    topology_name="CITY_DATA"
    feature_table="LAND_PARCELS"
    label_column="FEATURE_NAME"
    spatial_column="FEATURE"
    label_style="T.CITY NAME"
    render_style="C.COUNTIES"
    jdbc_srid="0"
    datasource="topology"
    asis="false">select feature, feature_name from land_parcels
  </jdbc_topology_query>
</theme>

OracleAS MapViewer also supports a debug mode that renders the nodes, edges, and faces of a topology. To specify debug mode, include the mode="debug" attribute in the <theme> element. In addition to the <jdbc_topology_query> attributes mentioned earlier in this section, the following attributes can be used in debug mode:

• edge_style attribute: Specifies the name of the style to be used to render edges.

• edge_label_style attribute: Specifies the name of the text style to be used to render edge labels.

• edge_marker_style attribute: Specifies the name of the marker style to be used for edge markers.

• edge_marker_size attribute: Specifies the size (number of pixels) of for edge markers.

• node_style attribute: Specifies the name of the style to be used to render nodes.

• node_label_style attribute: Specifies the name of the text style to be used to render node labels.

• face_style attribute: Specifies the name of the style to be used to render faces.

• face_label_style attribute: Specifies the name of the text style to be used to render face labels.

Example 2-23 defines a debug-mode topology theme for rendering features, edges, nodes, and faces from all feature tables in the CITY_DATA topology.

<theme name="topo_theme" mode="debug" user_clickable="false">
  <jdbc_topology_query
    topology_name="CITY_DATA"
    edge_style="C.RED"
    edge_marker_style="M.IMAGE105_BW"
    edge_marker_size="8"
    edge_label_style="T.EDGE"
    node_style="M.CIRCLE"
    node_label_style="T.NODE"
    face_style="C.BLUE"
    face_label_style="T.FACE"
    jdbc_srid="0"
    datasource="topology"
    asis="false">
  </jdbc_topology_query>
</theme>

INSERT INTO user_sdo_themes  VALUES (
   'LANDPARCELS',
   'Topology theme for land parcels',
   'LAND_PARCELS',
   'FEATURE',
   '<?xml version="1.0" standalone="yes"?>
    <styling_rules theme_type="topology" topology_name="CITY_DATA">
      <rule>
        <features style="C.RED"></features>
        <label column="FEATURE_NAME" style="T.TEXT STYLE"> </label>
      </rule>
    </styling_rules>' );

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 OracleAS MapViewer 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 OracleAS MapViewer) 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 OracleAS MapViewer) 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 OracleAS MapViewer 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 OracleAS MapViewer 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 OracleAS MapViewer 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 OracleAS MapViewer 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-25 in Section 2.4 includes min_scale and max_scale values.

To determine the current map scale for a map returned by OracleAS MapViewer, 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. OracleAS MapViewer assumes a typical screen resolution of 72 dpi. Because 72 pixels equals 1 inch, the height of the returned map is 4.86 inches (350/72 = 4.86). In this example, the size of the map is 10, and therefore the map scale is approximately 2.057 (10/4.86 = 2.057).

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 OracleAS MapViewer style, including advanced styles

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

<?xml version="1.0" standalone="yes"?>
<map_request
             basemap="density_map"
             datasource = "mvdemo">
  <center size="1.5">
     . . .
  </center>

  <legend bgstyle="fill:#ffffff;fill-opacity:128;stroke:#ff0000" 
          position="NORTH_WEST" font="Dialog">
    <column>
      <entry text="Map Legend" is_title="true"/>
      <entry style="M.STAR" text="center point"/>
      <entry style="M.CITY HALL 3" text="cities"/>
      <entry is_separator="true"/>
      <entry style="C.ROSY BROWN STROKE" text="state boundary"/>
      <entry style="L.PH" text="interstate highway"/>
      <entry text="County population:"/>
      <entry style="V.COUNTY_POP_DENSITY" tab="1"/>
    </column>
  </legend>

  <themes>
     . . .    
  </themes>
  
</map_request>  

Figure 2-6 Map with Legend

Description of "Figure 2-6 Map with Legend"

Notes on Example 2-26 and Figure 2-6:

• 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).

For detailed information about adding a legend to a map request, see Section 3.2.11.

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 Section 1.5.5.) The default position for a legend is SOUTH_WEST.

2.8.1 xxx_SDO_MAPS Views

The USER_SDO_MAPS and ALL_SDO_MAPS views have the columns listed in Table 2-3.

2.8.2 xxx_SDO_THEMES Views

The USER_SDO_THEMES and ALL_SDO_THEMES views have the columns listed in Table 2-4.

2.8.3 xxx_SDO_STYLES Views

The USER_SDO_STYLES and ALL_SDO_STYLES views have the columns listed in Table 2-5.

Depending on the Oracle Database release, the ALL_SDO_STYLES view may contain sample styles owned by the MDSYS schema. If these styles are defined on your system, you can specify them in theme definitions and map requests, and you can examine the XML definitions for ideas to use in defining your own styles.

To specify a style (or other type of OracleAS MapViewer object) that is owned by a schema other than the one for the current user, you must specify the schema name, and you must use a colon (:), not a period, between the schema name and the object name. The following excerpt from a <jdbc_query> element refers to the style named C.RED owned by the MDSYS schema:

<jdbc_query . . . render_style="MDSYS:C.RED">
. . .
 </jdbc_query>

Example 2-30 finds the names of all currently defined styles owned by the MDSYS schema, and it displays the type, description, and XML definition of one of the styles. (The example output is reformatted for readability.)

SELECT owner, name FROM all_sdo_styles 
  WHERE owner = 'MDSYS';
 
OWNER                            NAME
-------------------------------- --------------------------------
MDSYS                            C.BLACK
MDSYS                            C.BLACK GRAY
MDSYS                            C.BLUE
MDSYS                            C.COUNTIES
MDSYS                            C.FACILITY
. . .
MDSYS                            L.MAJOR STREET
MDSYS                            L.MAJOR TOLL ROAD
MDSYS                            L.MQ_ROAD2
MDSYS                            L.PH
MDSYS                            L.POOR_ROADS
MDSYS                            L.PTH
MDSYS                            L.RAILROAD
MDSYS                            L.RAMP
MDSYS                            L.SH
MDSYS                            L.STATE BOUNDARY
. . .
MDSYS                            M.REDSQ
MDSYS                            M.SMALL TRIANGLE
MDSYS                            M.STAR
MDSYS                            M.TOWN HALL
MDSYS                            M.TRIANGLE
MDSYS                            T.AIRPORT NAME
MDSYS                            T.CITY NAME
MDSYS                            T.MAP TITLE
MDSYS                            T.PARK NAME
MDSYS                            T.RED STREET
MDSYS                            T.ROAD NAME
MDSYS                            T.SHIELD1
MDSYS                            T.SHIELD2
MDSYS                            T.STATE NAME
MDSYS                            T.STREET NAME
. . .
 
-- Display the type, description, and XML definition of one style.
SET LONG 4000;
SELECT owner, name, type, description, definition 
  FROM all_sdo_styles WHERE name = 'L.PH';
 
OWNER   NAME     TYPE       DESCRIPTION
------  -----    ------     ------------------
MDSYS   L.PH     LINE       Primary highways
 
DEFINITION
---------------------------------------------------------------------------
<?xml version="1.0" standalone="yes"?>
<svg width="1in" height="1in">
<desc></desc>
<g class="line" style="fill:#33a9ff;stroke-width:4">
<line class="parallel" style="fill:#aa55cc;stroke-width:1.0"/>
</g>
</svg>