[McIDAS #KFB-284893]: Converting units in satellite data

Hi Carol,

re:
> Yes, we solved the original problem/confusion! Thanks for your help in
> doing the unit conversion in the BAR. That was what I was originally asking
> about. It's also really helpful to know about the abincalb.inc file. This
> will definitely be helpful in defining stretch tables in the future.

I'm happy that the previous information was of some help :-)

re:
> Right, so I had noticed a few weeks ago that the SU= keyword in the IMGDISP
> command for the L2 products was breaking things. I didn't really think too
> much about it since, I was mostly concerned about getting the BAR looking
> correct. I'm only using the SU= in the BAR command, which is why it's not
> changing the pixels/colors. That makes sense now!

OK.

re:
> Ok no rush on this. So long as I set up the stretch tables with the full
> range, these colors should match the BAR correctly as far as I understand.
> I'm not too interested in doing anything fancy within the stretch table, it
> just didn't make sense to me.

So, some good old fashioned exercise (I had to shovel the 9" of snow I got
up here on Sugarloaf... it is nice and heavy with water, a welcome 
infusion of moisture into a very dry landscape) helped me clear out the
cobwebs so that I can *hopefully* properly and fully explain a procedure
that I think you will want to adopt and use for your displays of 
GOES-R Level 2 products.

Here goes:

1) in McIDAS-X, a stretch table is used as a way of re-mapping the
   correspondence between any image unit and brightness

   Interrogation of an image using 'D' or the more generic 'IMGPROBE'
   commands is what one uses to list all of the units available for
   a particular image.

   In the case of Cloud Top Height Level 2 products, the units available
   are 'RAW', 'CTH' and 'BRIT'.

2) in order to use a stretch to change the mapping of unit to brightness,
   one needs to:

   - create a stretch table for the specific type of image

   - specify the use of the stretch table in the SU= keyword when 
     running IMGDISP

   Using a stretch like this _will_ change the colors for the pixel range
   specified in the stretch table.

   I'll give an example that demonstrates this below.

3) the use of a stretch table to change units listed in a BAR display
   is something that I added to BAR a long time ago after getting a
   strong request from a user in JOSS

   This kind of use of a stretch table is very different from the intended
   use referred to in 1) and 2).

So, let's do an example.

NB: in the following, I will use the NPGOESR ADDE dataset that is available
on lead.unidata.ucar.edu and atm.ucar.edu

a) display the most recent Cloud Top Height image from the NPGOESR dataset:

DATALOC ADD NPGOESR LEAD.UNIDATA.UCAR.EDU

DSINFO IMAGE NPGOESR

IMGLIST NPGOESR/CTHCN FORM=ALL
Image file directory listing for:NPGOESR/CTHCN
 Pos Satellite/         Date       Time      Center      Res (km)   Image_Size
     sensor                                 Lat  Lon    Lat   Lon
 --- -------------  ------------  --------  ---- ----  ----- ----- ------------
 288  GOES-16 L2    28 APR 21118  20:11:14    30   87
   Band: 3    L2: ACHA - Cloud Top Height              12.77 10.66   300 x  500
     proj:    0 created: 2021118 201114  memo: GOES ConUS - Mode 6
     type:ABIN     cal type:RAW
     offsets:  data=     768 navigation=  256 calibration=  768 auxiliary=  768
     doc length:   0   cal length:   0   lev length:   0 PREFIX=   0
     valcod:          0 zcor:  0 avg-smp: A
     lcor:    1  ecor:     1  bytes per pixel: 2  ss:187
     Resolution Factors (base=1):   Line=   20.0   Element=   20.0
IMGLIST: done

b) load the most recent NPGOESR/CTHCN image centered o Topeka, Ks and
   blown up by a factor of 2

SF 1
ERASE F
IMGDISP NPGOESR/CTHCN STA=KTOP PLACE=C MAG=2 EU=L2-ACHA
MAP
BAR

c) interrogate the image to see the list of 'units'

-- move the cursor to somewhere in the image and run the 'D'
   command

 

     Image Name           Day      Nominal Time   Scan Time    Band
  ----------------      -------    ------------   ---------    ----
  NPGOESR/CTHCN.288   28 Apr 21118   20:16:14      20:16:44       3

                        File     Nominal  Image     RAW         CTH         BRIT
       Lat/Lon      Line/Element  Line/Element                  M
 37:32:24/ 100:22:55    92/  157    1851/ 3151          19321        5897       
   76

IMGPROBE: Done

   This shows that the list of valid units is 'RAW', 'CTH' and 'BRIT'.

d) create a stretch that will change the mapping of 'CTH' to brightness

SU INI L2-CTH ABIN CTH

SU MAKE L2-CTH 1000 8000 0 255

SU TABLE L2-CTH
BREAKPOINTS STORED IN TABLE : L2-CTH.ST
INPUT       OUTPUT
-----       ------
 1000          0
 8000          255
CALIBRATION TYPE  : ABIN
CALIBRATION UNITS : CTH
BAND NUMBER       : -1
INTERPOLATION TYPE: LIN
SU: DONE

e) display the same image (it will be the same if a new one has not been
   added to the NPGOESR/CTHCN dataset, of course) using the stretch just
   created

SF 2
ERASE F
IMGDISP NPGOESR/CTHCN STA=KTOP PLACE=C MAG=2 EU=L2-ACHA SU=L2-CTH
MAP
BAR

f) setup a loop of the two images

LB 1 2
TERM L ON

This demonstrates the original/"standard" use of a stretch table.


Now, the original "feature" that I added to BAR was to be able to
specify a stretch table to use to change the labeling to some other
unit (e.g., FT instead of M).  I just tried this, and it doesn't work.
I then looked at the HELP for BAR, and I saw the following:

HELP BAR
BAR -- Displays a grayscale bar on a frame containing an image
   BAR frame <keywords>
Parameters:
   frame |  frame number (def=current)
Keywords:
   ANNot=NO | do not write text annotation, only the bar and label (def)
       =YES justify line ele color size "text | write text annotation on
                                                frame, where:
                  justify - justification of text; specify L, R or C,
                            where L=left, R=right, C=center (def=C)
                  line - beginning TV line to write text (def=7 on a
                         480x640 frame; def=computed on other sizes)
                  ele - beginning TV element to write text (def=320 on
                        a 480x640 frame; def=computed on other sizes)
                  color - graphics color level of text (def=3)
                  size - pixel size of text (def=11 on a 480x640 frame;
                         def=computed on other sizes)
                  "text - annotation text (def=memo field from
                          IMGLIST FORM=ALL; if the image also has an
                          INFO AUX block - like NEXRAD precip images -
                          it is written below the memo field text)
   COLor= | graphics color level for labels (def=3)
   GRA= | graphics frame to display labels (def=current if running
          McIDAS-X with independent graphics;  otherwise def=number
          specified in 'frame' parameter)
   LINt= | label interval; value must be greater than zero (def=computed)
   LSIze= | height of labels, in pixels (def=computed)
   ORIent=VER | bar is displayed vertically (def)
         =HOR | bar is displayed horizontally
   POSition=CUR  | draws bar that fills cursor at its current location
           =line ele short long | user-specified location and size, where:
               line  - starting TV line (def=computed)
               ele - starting TV element (def=computed)
               short - length, in pixels, of the bar's short axis
                       (def=computed)
               long  - length, in pixels, of the bar's long axis
                       (def=computed)
   RANge=min max | range of values to display in the bar (def=computed)
   SU= | name of the stretch table to apply to the grayscale bar
         (def=table specified in IMGDISP command)
Remarks:
 ...
   If the image was displayed with a stretch table (i.e., IMGDISP with
   SU keyword), the SU and RANGE keywords are ignored. If the image has
   an auxiliary block (e.g., NEXRAD Level III radar images), the RANGE
   keyword is ignored and the LINT keyword is valid only if the image
   was displayed with a stretch table.

   The following three rules determine the units of the labels:
     1. If the image was displayed with a stretch table, the label units
        are the same as the calibration units of the stretch table.
     2. If the image has an auxiliary block and was not displayed with
        a stretch table, the label units are the same as the units in
        the auxiliary block.
     3. If the image was not displayed with a stretch table and does
        not have an auxiliary block, the units are the same as the
        calibration units of the stretch table specified in the BAR
        command's SU keyword. If SU is not specified, the units are
        brightness values.

The thing to note is the last comments under Remarks.

I am not sure when the original feature of being able to label an
image differently was introduced into BAR (I do _not_ remember making
this mod), but it is there nonetheless.  :-(

Given the above, one either has to stick with the units in the
stretch when displaying an image using a stretch, or not use
a stretch when displaying the image, and then be free to change
the units shown in the BAR.

Argh!

Cheers,

Tom
--
****************************************************************************
Unidata User Support                                    UCAR Unidata Program
(303) 497-8642                                                 P.O. Box 3000
address@hidden                                   Boulder, CO 80307
----------------------------------------------------------------------------
Unidata HomePage                       http://www.unidata.ucar.edu
****************************************************************************


Ticket Details
===================
Ticket ID: KFB-284893
Department: Support McIDAS
Priority: Normal
Status: Closed
===================
NOTE: All email exchanges with Unidata User Support are recorded in the Unidata 
inquiry tracking system and then made publicly available through the web.  If 
you do not want to have your interactions made available in this way, you must 
let us know in each email you send to us.