User's Guide

DCW2RAS

Rasterize vector data from Digital Chart of the World

Function:

Rasterize vector data from the Digital Chart of the World (DCW) and either create a new image of line work that can be used as an overlay for the input image, copy the input image to a new image with line work overlaid on it, or write the line work directly into the input image. This routine places line work into AVHRR LAS images in satellite projection or LAS images in any projection. If the input image is in the AVHRR satellite's projection, its associated AVHRR Data Descriptor Record (ADDR) file must exist.

Parameters:

IN
Input image. The image for which the vector overlay is being generated. It must be a single band image if the vector data is to be overlaid onto the image (when OUT is NULL) or if the input image is to be copied to the output image with line work overlaid into it (BACKGRND is NULL). Subwindowing may be used in combination with ULCOOR and LRCOOR specifications. See User Note 2.

ULCOOR(--)
Upper left coordinate. The maximum latitude and minimum longitude, in degrees, of the area of interest. Lines which lie west or north of this coordinate will be excluded. If NULL, the upper left corner of the input image window will be used.

LRCOOR(--)
Lower right coordinate. The minimum latitude and maximum longitude, in degrees, of the area of interest. Lines which lie east or south of this coordinate will be excluded. If NULL, the lower right corner of the input image window will be used.

OUT
Output image. The output image will be a one-band image containing a background of BACKGRND values or the image data from IN, with lines of PIXVAL drawn over them. It will be the same data type as IN. When this parameter is NULL, the vector data is drawn directly into the input image.

CDPATH(/SGS4/DCW/DCW)
Compact Disk (CD) drive location. If the DCW is stored on CD, specify the location of the drive to read the CD. If the DCW is stored on disk, this value should define the root directory of the DCW data.

LIBRARY("NOAMER")
DCW Library. The DCW library that lines will be extracted from. The DCW is divided into four libraries. Each library exists on a single CD, or in a single directory on disk. These libraries are:

 
    = NOAMER:      North America
    = EURNASIA:    Europe and Northern Asia
    = SOAMAFR:     South America and Africa
    = SASAUS:      South Asia and Australia

PO(--)
Political boundaries and ocean features. The following fields may be selected for this feature:

  = --: No political boundaries
  =  1: International boundary, de jure
  =  2: International boundary, de facto
  =  3: International boundary, de jure & de facto
  =  4: Administrative boundary, primary
  =  5: Administrative boundary, major
  =  6: Treaty or occupancy line
  =  7: Coastal closure line
  =  8: Ocean demarcation line
  =  9: Ice line
  = 10: Coastline
  = 11: Ice/water line
  = 12: Sea wall
  = 13: International Date Line

DN(--)
Drainage feature. This feature category is very dense; only small areas should be rasterized with items from this feature. The following fields may be selected for this feature:

  = --: No drainage features
  =  1: Streams, rivers, etc.
  =  2: Inland shorelines
  =  3: Wet sand limits
  =  4: Canals, aqueducts, etc.
  =  5: Glacial limits
  =  6: Snow field, glacier
  =  7: Land/ice line

RD(--)
Road feature. The following fields may be selected for this feature:

  = --: No read features
  =  1: Dual lane highways
  =  2: Primary or secondary roads
  =  3: Tracks, trails, etc.

RR(--)
Railroad feature. The following fields may be selected for this feature:

  = --: No railroad features
  =  1: Single track railroad
  =  2: Multi-track railroad
  =  3: Light Railroad

HY(--)
Hypsography feature. The following fields may be selected for this feature:

  = --: No hypsography features
  =  1: Close land contour
  =  2: Depression contour
  =  3: Closed land, approximated
  =  4: Carrying contour
  =  5: Depression, approximated

HS(--)
Supplemental hypsography feature. The following fields may be selected for this feature:

  = --: No supplemental hypsography features
  =  1: Partial interim or auxiliary contour
  =  2: Partial depression contour
  =  3: Partial interim contour, approximated
  =  4: Carrying contour
  =  5: Cut or fill
  =  6: Unreliable
  =  7: Transition or mistake contour

PIXVAL(255)
Pixel value. The grey level value to be given to the rasterized vector data.

BACKGRND(0)
Background value. The value given to the pixels of the output image that are not assigned a value from the input vector data. If BACKGRND is NULL, the background of OUT will be filled with the pixel values from the input image. This parameter is ignored if OUT is NULL.

LINWT(1)
Line weight. The width, in number of pixels, of the rasterized line work.

PROJ(SAT)
Projection code. The projection type of IN.

  = SAT:  Satellite projection.  IN is in AVHRR
          satellite projection.  The image must have
          an associated ADDR file.
  = OTH:  All other projections.  Projection 
          information for the image is retrieved from
          the DDR.

PNTINT(1)
Point interval. By default, every PNTINT point from the DCW line segment will be used to generate line work in OUT. Increasing PNTINT will allow the user to generate an image more quickly, while maintaining relatively accurate line work. Each increment of PNTINT is about 40% faster than the previous PNTINT, until PNTINT exceeds five. With values larger than five, the speed increase is less noticeable. See User Note 3.

Examples:

  1. LAS> dcw2ras in=inimg out=outimg po=(1,2)

    OUTIMG will be a one-band image the same size as INIMG, containing international boundaries of North America. Since INIMG is in the satellite's projection, OUTIMG will be also.

  2. LAS> dcw2ras in="inimg(:2)" ulcoor=(45.0 -96.0) lrcoor=(40.0 -90.0) out=-- library=(noamer,soamafr) dn=1 pixval=1023 linwt=2

    Band two of INIMG will have line work drawn into the rectangle bounded by 45.0 latitude, -96.0 longitude and 40.0 latitude, -90.0 longitude. The rivers of North and South America will be drawn with a pixel value of 1023. Lines will be two pixels wide.

  3. LAS> dcw2ras in=inimg out=outimg library=soamafr po=4,5 backgrnd=-- proj=oth pntint=4

    The primary and major administrative boundaries of South America will be drawn into OUTIMG. The background of OUTIMG will be copied from INIMG. INIMG was reprojected, so OUTIMG will be in the same projection. Every fourth point of the DCW segments are selected.

  4. LAS> dcw2ras in=inimg(100 100 400 400:2) ulcoor=(40.0 -90.0) lrcoor=(20.0 -70.0) out=outimg po=4,5 backgrnd=-- proj=oth

    OUTIMG will be a 400 by 400 image whose background was copied from the specified window (100 100 400 400) of band 2 of IN. The primary and major administrative boundaries of North America in the rectangle bounded by 40.0 latitude, -90.0 longitude and 20.0 latitude, -70.0 longitude will be drawn into OUTIMG as they fall within the specified window. INIMG was reprojected, so OUTIMG will be in the same projection.

Description/Algorithm:

DCW files contain vector data of feature outlines. The data consists of a series of latitude/longitude pairs that are points along line segments. To "rasterize" the DCW vector data, each latitude/longitude point in the file is converted to a line/sample coordinate. The points are then connected to produce line segments.

Processing begins by opening a temporary scan file. The correct DCW files for the specified areas and features are opened. DCW is stored in files ("tiles") of line work covering a 15 degree by 15 degree area. The area of interest is divided into tiles, and each tile is read and rasterized individually. See User Note 1 for more information about tiles. While reading through the DCW file, whenever a line segment falls within the area of interest, the corresponding line and sample coordinates of every PNTINT point in that segment are calculated. The endpoints and line/sample values of pixels connecting these two points are written to the temporary scan file. After all the DCW files have been read, they are closed and the scan file is sorted.

If OUT is NULL, the line work will be drawn into the window specified in IN, otherwise it will be drawn into OUT. The raster image is opened and the sorted file is read. Line work is inserted into the raster image as it is being written. For each line in the sorted file, the appropriate pixels are set to PIXVAL, and the rest are set to BACKGRND or copied from IN if BACKGRND is NULL. If a new output image is being created, it will be a single-band image the same size and data type as IN. If no output image is specified, the lines will be overwritten into IN with a pixel value of PIXVAL.

Nonfatal Error Messages:

  1. [dcw2ras-outaddr] Error creating ADDR file for OUT

    An error occurred while creating an AVHRR DDR file for OUT. This file may be necessary if OUT will in turn be processed using ADAPS functions.

Fatal Error Messages:

  1. [dcw2ras-alloc] Error allocating dynamic memory

    An error occurred dynamically allocating memory, which was required for further processing. Contact the system administrator if the problem persists.

  2. [dcw2ras-calc] Cannot calculate <minimum/maximum> <latitude/longitude>

    An error occurred trying to calculate the specified coordinate of the projected input image. Specify a window for IN or specify corner coordinates using ULCOOR and LRCOOR.

  3. [dcw2ras-cover] Could not find coverage information

    Coverage information for the specified area and features could not be found. Verify that CDPATH is the correct location of the DCW files.

  4. [dcw2ras-empty] No vector data occurs in the output image

    After scanning all lines in the specified DCW files, no segments were found to fall in the specified area. Check that the specified LIBRARY covers the area of the scene.

  5. [dcw2ras-fatal] Fatal error encountered

    A fatal error was encountered during processing. The preceding message explains the exact error.

  6. [dcw2ras-onebnd] Only a single band image allowed on input

    This error may occur in two cases. One band of IN must be specified when OUT is NULL, because the line work is placed directly into IN. If OUT is specified and BACKGRND is NULL, one band from IN must be specified from which background data will be taken. Retry, either by specifying a new image in OUT or by specifying one band in IN.

  7. [dcw2ras-opnscn] Error opening scan file

    An error occurred opening a file into which line segments will be placed. Check to ensure there is sufficient disk space and that you have write permission in the current working directory.

  8. [dcw2ras-proj] Invalid projection information in DDR

    PROJ was specified as "OTH", but the input image's DDR has invalid values. Verify that the image DDR has valid values for the projection code, corner coordinates, projection distance, and projection unit. If not, reproject the image, or use the "SAT" satellite projection.

  9. [dcw2ras-query] Error occurred querying DCW

    An error occurred retrieving lines from DCW. This occurs for one of two reasons: the correct DCW files could not be found, or the system ran out of memory for its list of lines. Verify that all DCW files exist, and contact the system administrator if the problem persists.

  10. [dcw2ras-range] <XXX> is not within the valid range for <YYY> data

    The value specified for BACKGRND or PIXVAL was not within the valid range for the data type of IN. Retry, using a different value for BACKGRND/PIXVAL.

  11. [dcw2ras-system] System file sort failed

    An error occurred while sorting the scan file of line segments. Check to ensure there is sufficient disk space to write another file the same size as the scan file.

  12. [dcw2ras-update] Compressed image cannot be opened for update

    This error will occur if IN is a compressed image and OUT is NULL. Either create a new output image using OUT, or use COPY to create an uncompressed copy of IN.

  13. [dcw2ras-values] <XXX> must have 0 or 2 values

    ULCOOR and LRCOOR must be left NULL or specified as a latitude/longitude pair.

User Notes:

  1. Some DCW line work features are very dense. When rasterizing lines over a large area, the area is divided up into 15 x 15 degree "tiles". The DCW lines are read and rasterized one tile at a time to avoid running out of memory. This process is relatively slow. It is recommended that only small areas be rasterized for dense features such as DN=(1,2).

  2. Users may use a combination of two methods of restricting areas for line work: subwindowing IN, and specifying an area using ULCOOR and LRCOOR. If IN is subwindowed, line work will only appear in the specified window, and if OUT is specified, it will be the size of IN's window. If ULCOOR and LRCOOR are specified, the line work will be limited to this area even if it is smaller than the area of IN's window. If ULCOOR and LRCOOR are not specified, they will be set to the minimum and maximum latitude and longitude of the specified window. ULCOOR and LRCOOR always take precedence over IN's window for limiting the area of line work.

  3. Increasing PNTINT will allow the user to generate an image more quickly. Each increment of PNTINT is noticeably faster than the previous, up to PNTINT=5. After that, the speed increase is less noticeable. For example, specifying PNTINT=5 will generally complete in one-third to one-fourth the time of PNTINT=1. The line work will be relatively accurate but the lines may appear more "jagged" as the distance between points increases.

  4. To overlay line work into IN, OUT must be set to NULL. To create a new image of line work, OUT must be specified.

  5. For more information about the DCW, refer to the Military Specification, Digital Chart of the World, MIL-D-89009 and to the Military Standard, Vector Product Format, MIL-STD-600006.

  6. Similar routines are WDB2RAS, DCW2TAB, and TAB2RAS.