embedCont

Description

embedCont is a utility for “burning” or embedding vector data, such as contour lines or ship tracks, directly into a JHC-format 8-bit grid file (i.e., an image or mosaic). It reads line segments from a vector file and draws them onto the raster image, modifying the image file in place. This is often used as a final step in map production to overlay line work on a base image.

Usage 

embedCont [OPTIONS] <8bit_mapsheet_file> <vector_file>

Arguments

Option Description Default / Example
<8bit_mapsheet_file> Required. The 8-bit JHC grid file (e.g., .mos, .8bit) that will serve as the background image. This file is modified in place. background_mosaic.mos
<vector_file> Required. The file containing the vector data to be drawn. The format is specified by other options (see below). contours.bin
-col <value> Specifies the 8-bit color value (0-255) to be used for drawing the lines. -col 255 (white)
-linethick <pixels> Sets the thickness of the drawn lines in pixels. -linethick 2
-ascii Specifies that the input <vector_file> is an ASCII text file. The tool expects each line to contain latitude longitude value. It connects consecutive points to form lines.  
-pixel_coords Used with -ascii. Interprets the ASCII input as x y value in pixel coordinates instead of geographic lat lon value.  
-isheader Specifies that the input <vector_file> is another JHC grid file. embedCont will read its header and draw its rectangular geographic bounding box onto the mapsheet. This is useful for creating index plots.  
-buf <pixels> Used with -isheader. Allows the bounding box to be drawn even if it lies partially outside the main mapsheet’s boundaries, by the specified pixel buffer amount. -buf 100
-maxlen_m <meters> A filter that prevents the tool from drawing any single vector segment that is longer than the specified length in meters. This is useful for cleaning up artifacts or gaps in contour or trackline data. -maxlen_m 1000
-v Enable verbose output.  

How It Works

  1. File Opening: Opens the input 8-bit mapsheet file for reading and writing (in-place modification). Opens the vector file for reading.
  2. Header Reading: Reads the JHC_header from the mapsheet file. If -isheader is used, it also reads the header from the vector file.
  3. Vector Data Processing: Reads the vector data from the vector_file based on its format:
    • Binary Vector (default): Reads custom binary line segments.
    • ASCII Coordinates (-ascii): Reads latitude longitude value (or x y value if -pixel_coords) and converts to pixel coordinates.
    • JHC Header (-isheader): Extracts geographic bounds from the vector file’s header and converts them to pixel coordinates to draw a bounding box.
  4. Rasterization: For each line segment in the vector data:
    • It projects the coordinates to pixel coordinates on the mapsheet.
    • If -maxlen_m is specified, it filters out segments longer than the maximum allowed length.
    • It then uses do_DDA_raster_line or do_raster_line (from array.c) to draw the line onto the 8-bit mapsheet array with the specified col and linethick.
  5. Output: The input 8-bit mapsheet file is modified in-place.

Output Files

The input 8-bit mapsheet file (<8bit_mapsheet_file>) is modified in-place.

Dependencies

  • array.h: For JHC_header structure and raster line drawing functions.
  • support.h: For general utility functions and error handling.
  • j_proj.h: For coordinate projection functions.

Notes

This tool is effective for combining vector-based information (like survey lines, contours, or boundaries) with raster base maps, producing integrated map products. The do_DDA_raster_line and do_raster_line functions provide optimized routines for drawing lines on 8-bit image arrays. maxlen_m is particularly useful for cleaning noisy vector data that might contain spurious long segments.

Input Vector Formats

embedCont supports three types of input for the <vector_file>:

  1. Binary Vector (default): A custom OMG-HDCS binary format (.bin) containing a series of line segments with associated values. This is the format generated by tools like contgrid.
  2. ASCII Coordinates (-ascii): A simple text file with geographic points that are connected sequentially.
  3. JHC Header (-isheader): Any JHC grid file, from which only the header’s geographic extent is used to draw a box.