User's Guide

ANNOTATE

Insert annotation into an image at specified locations.

Function:

Inserts horizontal or vertical text annotations into an image. The user may specify up to twenty text strings of 264 characters or less and their line/sample locations. The size of the characters, the grey value for the characters, and the grey value for the background may also be specified. Annotation may be placed on an existing image, the input image may be copied and then annotations applied, or a new image with annotations may be created.

Parameters:

Subcommand -INPLACE:
Places annotation in the input image, annotates the image in place. Subbanding is allowed but windowing is not.

IN
Input image. Image that the annotation is to be placed on. Subbanding is allowed but windowing is not.

ANNOTE
Annotation text. Text string(s) to be inserted into the image. The maximum string length is 264 characters. Each text string will consist of two consecutive parameter values concatenated together. (The string is split in two because the maximum TAE string length is 132.) See User Note 2.

SL
Starting line. The starting line within the image where the corresponding text string will start. There must be one value for each string specified in ANNOTE. SL and SS together specify the location of the top left corner of the annotation text.

SS
Starting sample. The starting sample within the corresponding image line where the corresponding text string will start. There must be one value for each string specified in ANNOTE. SL and SS together specify the location of the top left corner of the annotation text.

FONT
Size of the font. 

  = FONT1:   8 x 10 (cellwide x cellhigh)
  = FONT2:  13 x 24                       
  = FONT3:  22 x 40
  = FONT4:  26 x 48
  = FONT5:  32 x 58

SCALFACT(--)
Annotation scale factor. The scale factor that determines the character cell size for the annotation text.

ANOTDIR(HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR)
Annotation direction. The direction of the text strings on the image. There must be one direction for each of the annotation strings. 

  = HOR:   Horizontal.  The text strings will be inserted horizontally 
           on the image.
  = VERT:  Vertical.  The text strings will be inserted vertically on 
           the image.

CHARGREY(--)
Character grey value. The grey value for the characters in each annotation text. All characters for a given annotation will have the same grey value. The default grey value is 255.

BACKGRND(--)
Background grey value. The grey value for the background of the annotations. A small rectangular area slightly larger than each annotation string will form each background region. If defaulted, the background will be the original image.
Subcommand -INOUT:
Copies the input image and inserts annotations in the output image. The original image thereby remains intact.

IN
Input image. The image to be copied. Subbanding and windowing are allowed.

OUT
Output image. The output image will be the same size and data type as IN.

ANNOTE
Annotation text. Text string(s) to be inserted into the image. The maximum string length is 264 characters. Each text string will consist of two consecutive parameter values concatenated together. (The string is split in two because the maximum TAE string length is 132.) See User Note 2.

SL
Starting line. The starting line within the image where the corresponding text string will start. There must be one value for each string specified in ANNOTE. SL and SS together specify the location of the top left corner of the annotation text.

SS
Starting sample. The starting sample within the corresponding image line where the corresponding text string will start. There must be one value for each string specified in ANNOTE. SL and SS together specify the location of the top left corner of the annotation text.

FONT(FONT1)
Size of the font. 

  = FONT1:   8 x 10 (cellwide x cellhigh)
  = FONT2:  13 x 24                       
  = FONT3:  22 x 40
  = FONT4:  26 x 48
  = FONT5:  32 x 58

SCALFACT(--)
Annotation scale factor. The scale factor that determines the character cell size for the annotation text.

ANOTDIR(HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR)
Annotation direction. The direction of the text strings on the image. There must be one direction for each of the annotation strings. 

  = HOR:   Horizontal.  The text strings will be inserted horizontally 
           on the image.
  = VERT:  Vertical.  The text strings will be inserted vertically on 
           the image.

CHARGREY(--)
Character grey value. The grey value for the characters in each annotation text. All characters for a given annotation will have the same grey value. The default grey value is 255.

BACKGRND(--)
Background grey value. The grey value for the background of the annotations. A small rectangular area slightly larger than each annotation string will form each background region. If defaulted, the background will be the original image.
Subcommand -GENIMG:
Generates a new image and applies annotations on it. The image specified by OUT will be generated as a single-band, BYTE image with a user-specified background value. The annotations will be placed on the BYTE image.

OUT
Output image. The output image will be a single band BYTE image.

ANNOTE
Annotation text. Text string(s) to be inserted into the image. The maximum string length is 264 characters. Each text string will consist of two consecutive parameter values concatenated together. (The string is split in two because the maximum TAE string length is 132.) See User Note 2.

SL
Starting line. The starting line within the image where the corresponding text string will start. There must be one value for each string specified in ANNOTE. SL and SS together specify the location of the top left corner of the annotation text.

SS
Starting sample. The starting sample within the corresponding image line where the corresponding text string will start. There must be one value for each string specified in ANNOTE. SL and SS together specify the location of the top left corner of the annotation text.

FONT(FONT1)
Size of the font. 

  = FONT1:   8 x 10 (cellwide x cellhigh)
  = FONT2:  13 x 24                       
  = FONT3:  22 x 40
  = FONT4:  26 x 48
  = FONT5:  32 x 58

NL(512 )
Number of lines. The number of lines in the output image.

NS(512 )
Number of samples. The number of samples per line in the output image.

PIXVAL(1)
Pixel value. The value to assign to each of the pixels in the generated image before it is annotated.

SCALFACT(--)
Annotation scale factor. The scale factor that determines the character cell size for the annotation text.

ANOTDIR(HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR HOR)
Annotation direction. The direction of the text strings on the image. There must be one direction for each of the annotation strings. 

  = HOR:   Horizontal.  The text strings will be inserted horizontally 
           on the image.
  = VERT:  Vertical.  The text strings will be inserted vertically on 
           the image.

CHARGREY(--)
Character grey value. The grey value for the characters in each annotation text. All characters for a given annotation will have the same grey value. The default grey value is 255.

BACKGRND(--)
Background grey value. The grey value for the background of the annotations. A small rectangular area slightly larger than each annotation string will form each background region. If defaulted, the background will be the original image.

Examples:

  1. LAS> annotate-inplace in=myfile annote=("this is image",, "number one") sl=(1 13) ss=(100 100) scalfact=(1 2)

    All bands of image MYFILE are annotated. The first text string, "this is image", is located at line 1, sample 100, and is the normal size of the default FONT1. The second string, "number one", is located at line 13, sample 100, and is twice the normal size of FONT1 (double the size of the first string). Both text strings default to the horizontal direction with character grey value 255; the input image forms the background for the characters.

  2. LAS> annotate-inout in=myfile out=mycopy annote=("this is a copy",, "of myfile") sl=(150 16) ss=(190 230) font=font2 scalfact=(1 1) chargrey=(0 0) backgrnd=255 anotdir=("hor" "vert")

    All bands of image MYFILE are copied to image MYCOPY which is then annotated. The first text string, "this is a copy", is located at line 150, sample 190, and uses the normal size of FONT2. The second string, "of myfile", is located at line 16, sample 230, and is also the normal size of FONT2. Both text strings have a character grey value of 0 and background grey value of 255. The first text string is positioned horizontally while the second is positioned vertically.

  3. LAS> annotate-genimg out=myfile nl=1500 ns=2500 annote=("new test",, "text number one") sl=(1 1) ss=(1 977) font=font3 pixval=128 scalfact=(2 2) anotdir=("vert" "vert") chargrey=(200 200) backgrnd=0

    A single-band BYTE image, MYFILE, is generated with size 1500 lines by 2500 samples and brightness value 128. The first text string, "new test", is located at line 1, sample 1, and is two times the normal size of FONT3. The second string, "text number one", is located at line 1, sample 977, and is two times the normal size of FONT3. Both text strings have a character grey value of 200 and background value of 0. Both text strings are positioned vertically.

Description/Algorithm:

Font1's annotated character is represented by an 8 x 10 pixel cell. This cell includes a one pixel border on the right and bottom edges of each character as illustrated by the following figure for the character "A": 

       Y Axis Pixel    X Axis Pixel
       ------------   ---------------
                      1 2 3 4 5 6 7 8

             1        . . . X . . . .
             2        . . X . X . . .
             3        . X . . . X . .
             4        X . . . . . X .
             5        X X X X X X X .
             6        X . . . . . X .
             7        X . . . . . X .
             8        X . . . . . X .
             9        X . . . . . X .
            10        . . . . . . . .


        Key:
        X  foreground pixels
        .  background pixels

Font2 through 5 annotated character is represented by a font with either a 13x24, 22x40, 26x48 or 32x58 array of points.

The font uses the last four columns as character separation. Also, the last 13 lines are used for characters that extend below the horizontal line such as letters "j", "p","q", etc. An example using FONT3 (22 wide x 40 high) for the letter "A" is: 


                               1 1 1 1 1 1 1 1 1 1 2 2 2
             1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2
           1 . . . . . . . X X X X . . . . . . . . . . .
           2 . . . . . . . X X X X . . . . . . . . . . .
           3 . . . . . . X X X X X X . . . . . . . . . .
           4 . . . . . . X X X X X X . . . . . . . . . .
           5 . . . . . . X X X X X X . . . . . . . . . .
           6 . . . . . X X X X X X X X . . . . . . . . .
           7 . . . . . X X X . . X X X . . . . . . . . .
           8 . . . . . X X X . . X X X . . . . . . . . .
           9 . . . . X X X X . . X X X X . . . . . . . .
          10 . . . . X X X . . . . X X X . . . . . . . .
          11 . . . . X X X . . . . X X X . . . . . . . .
          12 . . . . X X X . . . . X X X . . . . . . . .
          13 . . . X X X X . . . . X X X X . . . . . . .
          14 . . . X X X . . . . . . X X X . . . . . . .
          15 . . . X X X . . . . . . X X X . . . . . . .
          16 . . . X X X . . . . . . X X X . . . . . . .
          17 . . X X X X . . . . . . X X X X . . . . . .
          18 . . X X X X X X X X X X X X X X . . . . . .
          19 . . X X X X X X X X X X X X X X . . . . . .
          20 . . X X X X X X X X X X X X X X . . . . . .
          21 . X X X X . . . . . . . . X X X X . . . . .
          22 . X X X . . . . . . . . . . X X X . . . . .
          23 . X X X . . . . . . . . . . X X X . . . . .
          24 . X X X . . . . . . . . . . X X X . . . . .
          25 X X X X . . . . . . . . . . X X X X . . . .
          26 X X X . . . . . . . . . . . . X X X . . . .
          27 X X X . . . . . . . . . . . . X X X . . . .
          28 . . . . . . . . . . . . . . . . . . . . . .
          29 . . . . . . . . . . . . . . . . . . . . . .
          30 . . . . . . . . . . . . . . . . . . . . . .
          31 . . . . . . . . . . . . . . . . . . . . . .
          32 . . . . . . . . . . . . . . . . . . . . . .
          33 . . . . . . . . . . . . . . . . . . . . . .
          34 . . . . . . . . . . . . . . . . . . . . . .
          35 . . . . . . . . . . . . . . . . . . . . . .
          36 . . . . . . . . . . . . . . . . . . . . . .
          37 . . . . . . . . . . . . . . . . . . . . . .
          38 . . . . . . . . . . . . . . . . . . . . . .
          39 . . . . . . . . . . . . . . . . . . . . . .
          40 . . . . . . . . . . . . . . . . . . . . . .

          Key:  
          X  foreground pixels
          .  background pixels

The input parameter of SCALFACT will allow all 5 fonts to be scaled.

Note that there is no border around the top and left edges of the annotated text. If the image background and the character pixel values are similar, then the left and top edges of the annotated text may blend into the image. This artifact is illustrated with an example image that appears in the online html (Mosaic) help and the hardcopy user guide. Also illustrated is the appearance of text using a dark image for background.

If the background grey value (BACKGRND) is defaulted, the foreground character data overwrites the input pixels. If any other value is selected for BACKGRND, the entire character cell is overwritten with foreground and background pixels. The user may vary the size of the characters. If the annotation text does not fit within the bounds of the image a fatal error results.

ANNOTATE supports the following characters: 

        SP  !  "  #  $  %  &  '  (  )  *  +  ,  -  .  /
        0  1  2  3  4  5  6  7  8  9  :  ;  <  =  >  ?
        @  A  B  C  D  E  F  G  H  I  J  K  L  M  N  O
        P  Q  R  S  T  U  V  W  X  Y  Z  [  \  ]  ^  _
        `  a  b  c  d  e  f  g  h  i  j  k  l  m  n  o
        p  q  r  s  t  u  v  w  x  y  z  {  |  }  ~

The single back quote (`) and tab characters are not supported and will cause a fatal error.

Nonfatal Error Message:

    None.

Fatal Error Messages:

  1. [annotate-alloc] Error allocating dynamic memory

    An error occurred allocating memory. Rerun ANNOTATE, and if the error recurs, contact the system manager.

  2. [annotate-badchar] The <x> character is unsupported

    ANNOTATE does not allow for single back quote (`) and tab characters in the annotation text. The specified character was encountered.

  3. [annotate-fatal] Fatal error encountered

    A fatal error was encountered. The message displayed preceding this message was the error encountered. Processing terminates.

  4. [annotate-number] Number of values for <xxxxx> is less than that for ANNOTE

    The number of values for the named parameter must not be less than the number of text strings.

  5. [annotate-size] Images must have the same size

    The input images must be the same size. Respecify the windows and rerun.

  6. [annotate-textlen] Characters in string <x> extend beyond the image's <yyyyy>

    If any portion of a text string extends beyond the image, this message indicates which of the text strings is in error. Also identified is whether the text extends beyond the image's bottom or beyond the right edge.

  7. [annotate-wind] Window specification not allowed

    ANNOTATE-INPLACE does not allow for window specifications. The user should execute ANNOTATE-INOUT instead.

User Notes:

  1. The size of the annotated character cell characters varies with SCALFACT and FONT. The following table illustrates SCALEFACT using FONT2 as an example. 

            SCALFACT   Character Cell Size
        --------   -------------------
                   Samples      Lines
                   -------      -----
           1          13         24 
           2          26         48 
           3          39         72 
           4          52         96 
           5          65        120 
           6          78        144 
           7          91        168 
           8         104        192
         ...
          64         832       1536

  2. The user must use caution when more than one text string is to be inserted. For example, consider the following assignments: 

           1) ANNOTE=("first text",     "second text")
       2) ANNOTE=("first text",,    "second text")
       3) ANNOTE=("first text", "", "second text")

    The first example defines one text string: "first textsecond text". The second and third examples define two text strings of which the first one is "first text" and the second one is "second text".

  3. ANNOTATE optionally runs the COPY and TESTGEN modules. Refer to these user guides for additional error messages.

  4. ANNOTATE opens the images for update access. As a result, they must not have been created with compression enabled ($COMPFLG="ON"). The user must disable image compression by setting the TAE global $COMPFLG to "OFF".