This page was created by the IDL library routine `mk_html_help2`.

Last modified: Sat Aug 30 18:17:50 2025.

# Directory Listing of Routines

# general/misc/system

- COLOR_TABLE
  Returns the current color table as a 256x3 array.
- COLOR_TABLE_CRIB
- CWD
- GET_LINE_COLORS
- INIT_DEVICES
- INITCT
  Wrapper for loadct2 and loadcsv. Calls the appropriate color table
- LIBS
- LINE_COLORS
- LOADCT2
- SHOWCT
- THMCTPATH
  Gets the path of the color table used by themis

# Routine Descriptions

## COLOR_TABLE

[Next Routine] [List of Routines]

    FUNCTION:   color_table
    PURPOSE:
      Returns the current color table as a 256x3 array.

    USAGE:
      ctab = color_table()

    INPUTS:
           None.

    KEYWORDS:
           None.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-05-16 16:31:53 -0700 (Tue, 16 May 2023) $
     $LastChangedRevision: 31865 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/system/color_table.pro $

    Created by David L. Mitchell (May 2023)

(See general/misc/system/color_table.pro)

## COLOR_TABLE_CRIB

[Previous Routine] [Next Routine] [List of Routines]

    CRIB for managing color tables and line colors and taking control of colors in tplot

    ROUTINES:
       initct : Wrapper for loadct2 and loadcsv.  Works the same way as loadct2 and loadcsv,
                but provides access to both sets of color tables.  Provides keywords for
                setting line colors.  The previous routines still exist and can still be
                called as before, so there's no need to modify any code unless you want to.
       showct : Display the current color table or any color table with any line color scheme.
                Also shows a catalog of color tables as a grid of color bars.
       revvid : Swaps the values of !p.background and !p.color.
       line_colors : Choose one of 11 predefined line color schemes, or define a custom scheme.
       get_line_colors : Returns a 3x8 array of the current line colors [[R,G,B],[R,G,B], ...].
                         Can also return the 3x8 array for any line color scheme.
       color_table : Returns the current color table as a 256x3 array.

    HELPER ROUTINE:
       tsnap:   Plots Y-Z cuts through any tplot color spectrogram at times (X) selected by
                the mouse.  Plots error bars if DY is specified in the tplot variable.
                Also averages data in time and propagates errors, if desired.  Use this to
                determine if color variations are significant.

       See the headers of these routines for more details.

    OVERVIEW:

       Chances are you have a TrueColor display that can produce 256^3 = 16,777,216 colors by
       adding red, green and blue levels, each from 0 to 255.  Tplot and many associated
       routines use a color table, which is a 3x256 array consisting of a small subset of the
       possible colors.  Tplot reserves eight colors: one for the foreground color, one for the
       background color, and six for drawing lines.  The rest make up the color table:

           Color           Purpose                             Modify With
          --------------------------------------------------------------------------
             0             black (or any dark color)           initct, line_colors
            1-6            fixed line colors                   initct, line_colors
            7-254          color table (bottom_c to top_c)     initct
            255            white (or any light color)          initct, line_colors
          --------------------------------------------------------------------------

       Colors 0 and 255 are usually associated with !p.background and !p.color.  For a light
       background, set !p.background = 255 and !p.color = 0.  Do the opposite for a dark
       background.  Use revvid to toggle between these options.

       There are many possible color tables, because each table uses only 248 out of more than
       16 million available colors.  The standard catalog has table numbers from 0 to 74, while
       the CSV catalog has table numbers from 0 to 118.  These ranges overlap, so we need some
       way to separate them.  I chose to add 1000 to the CSV table numbers, so CSV table 78
       becomes 1078, etc.  There is also substantial overlap in the tables themselves:

            Standard Tables      CSV Tables       Note
          ----------------------------------------------------------------
                0 - 40           1000 - 1040      identical or nearly so
               41 - 43           1041 - 1043      different
               44 - 74           1044 - 1074      identical
                 N/A             1075 - 1118      unique to CSV
          ----------------------------------------------------------------

       When tables are "nearly identical", only a few colors are different.  The nearly identical
       tables are: [24, 29, 30, 38, 39, 40] <-> [1024, 1029, 1030, 1038, 1039, 1040].  So, apart
       from a few slight differences, there are 122 unique tables.

       Table 43 is a custom rainbow-like table designed at SSL.  The standard rainbow table (34)
       is problematic because it contains a large "dead zone", where many of the color values are
       hues of green that are hard to distinguish.  Important features of the data can be lost in
       this dead zone.  Table 43 is designed to have roughly the same number of table entries for
       each of the distinguishable colors (magenta, blue, cyan, green, yellow, orange, red) and
       to extend the overall dynamic range with fade-to-black and saturate-to-deep-red.  This
       table minimizes dead zones and is good for showing variations over a wide dynamic range;
       however, it has a double-peaked intensity curve and is not suitable for the color blind.
       It's worth comparing this table with an intensity-based table, such as 1074.  Each table
       has its pros and cons.

       Table numbers 49-65 (standard), 1049-1065 (CSV), and 1075-1116 (CSV) encode intensity on
       a monotonically increasing or decreasing scale, with color as a secondary feature.  These
       are useful for displaying data where intensity is the most important attribute.

       Table numbers 66-74 (standard) and 1066-1074 (CSV) are cross-fade tables, starting with a
       deep shade of one color and ending with a deep shade of a different color, with the peak
       intensity in the center.  Table 74 (or 1074) reversed is similar to a rainbow table.  Its
       single-peaked intensity curve is good perceptually; however, it has a dead zone from light
       green to yellow to light orange, which makes up about 25% of the table, so it's not good
       for showing variations in the middle of the dynamic range (same problem as table 34).

       Table numbers 1117 and 1118 are cyclical, with the top and bottom colors the same.  These
       tables are useful for displaying phase data (0 to 360 degrees).

       In addition to the standard and CSV catalogs, you can also choose the SPP Fields catalog
       which is based on the CET catalog (https://colorcet.com/index.html).  The SPP catalog has
       the same goals as the CSV catalog, but has a different set of intensity, cross-fade, and
       cyclical tables.  In particular, the SPP catalog has more cross-fade and cyclical options.

       As of this writing, there are 12 predefined line color schemes:

            0  : primary and secondary colors [black, magenta, blue, cyan, green, yellow, red, white]
           1-4 : four different schemes suitable for colorblind vision
            5  : same as 0, except orange replaces yellow for better contrast on white
            6  : same as 0, except gray replaces yellow for better contrast on white
            7  : https://www.nature.com/articles/nmeth.1618, except no reddish purple
            8  : https://www.nature.com/articles/nmeth.1618, except no yellow
            9  : same as 8 but permuted so vector defaults are blue, orange, reddish purple
           10  : Chaffin's CSV line colors, suitable for colorblind vision
           11  : same as 5, except a darker green for better contrast on white

       More schemes can be added by including them in the initialization block of get_line_colors.pro.
       Always add new schemes at the end of the list, so you don't break anyone else's code.  It's
       helpful if you can add a note about your scheme.

       Use showct to preview any color table with any line color scheme.  It's always best to try out
       different color tables on the actual data to evaluate what conveys the important features best
       without being misleading.  (The most important person not to mislead is yourself.)  There is
       no substitute for plotting cuts through the color spectrogram with symbols and error bars.
       This allows you to determine if a change in color is statistically significant.  There is a
       generic routine that plots cuts through any tplot color spectrogram at times selected by the
       mouse: tsnap.pro (see that routine's header for more information).

       Tplot has been modified to use initct and line_colors, so you can set custom color tables
       and line color schemes for individual tplot variables using options.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-05-25 12:08:33 -0700 (Sun, 25 May 2025) $
     $LastChangedRevision: 33340 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/system/color_table_crib.pro $

     Created by David Mitchell;  February 2023

    ro color_table_crib

     print, 'This routine is not intended to be a procedure.  Read the contents instead.'
     return

    ; Place the following lines in your idl_startup.pro to initialize your device and color
    ; table.  Of course, you can choose any of >100 color tables (reversed if desired), any of
    ; the predefined line color schemes, or completely custom line colors.  This example sets a
    ; dark background, but many people prefer a light background.

    evice,decompose=0,retain=2   ; specific to MacOS (settings for other OS's might be different)
                                 ;   decompose=0 --> use color table with TrueColor display
                                 ;   retain=2 --> IDL provides backing store (safest option)
    nitct,1074,line=5,/rev,/sup  ; define color table and fixed line colors (suppress error message)
    p.background = 0             ; use tplot fixed color for background (0 = black by default)
    p.color = 255                ; use tplot fixed color for foreground (255 = white by default)

    ; To use color tables with the Z buffer, do the following:

    et_plot, 'z'                            ; switch to virtual graphics device
    evice, set_pixel_depth=24, decompose=0  ; allow the Z buffer to use color tables

    ; Change the color table at the command line.  This does not alter the line color scheme,
    ; which is persistent until you explicitly change it.

    nitct, 1091

    ; Select a new color table and line color scheme at the command line.

    nitct, 43, line=2

    ; Change line colors without otherwise modifying the color table.

    ine_colors, 6

    ; Swap !p.background and !p.color

    evvid

    ; Use gray instead of white for the background, which looks better in some situations.
    ; The default gray level is [211,211,211].

    evvid, /white  ; if needed
    ine_colors, 5, /graybkg

    ; Use a custom gray level for the background.

    evvid, /white  ; if needed
    ine_colors, 5, graybkg=[198,198,198]

    ; Poke arbitrary RGB colors into indices 1 and 4 of the current line color scheme.

    ine_colors, mycolors={ind:[1,4], rgb:[[198,83,44],[18,211,61]]}

    ; Use an intensity-based, rainbow-like color table (1074).  Reverse the table, so that blue is
    ; low and red is high.  Use line colors suitable for the color blind.

    nitct, 1074, /reverse, line=8

    ; Choose the SPP Fields color table catalog.  Once you change the color table catalog,
    ; it remains in effect until you use initct to change it.  You can also select the SPP Fields
    ; color tables by setting the environment variable IDL_CT_FILE.

    nitct, 123, /spp

    ; Display the current color table with an intensity plot.

    howct, /i

    ; Display any color table with any line color scheme.  Unlike initct, this does not make any
    ; changes to the color table or line colors.

    howct, 1078, line=8, /i
    howct, 1091, line=5, /reverse, /graybkg, /i

    ; Display a catalog of color tables as a grid of color bars in a separate window.  Also show
    ; the current color table and corresponding intensity plot.

    howct, /i, /cat

    ; Show the SPP Fields catalog and a color table from that catalog.

    howct, 123, /i, /cat, /spp

    ; Following one of these commands, you can omit the CAT keyword and use showct to take a close
    ; look at any of the tables in the catalog while the catalog window is still visible.  Keep in
    ; mind what you are trying to convey with color.  Is it variations over a wide dynamic range,
    ; or intensity, or something else?  See https://colorcet.com/index.html for tips on choosing
    ; a good color table.

    howct, 125, /i, /spp
    howct, 84, /reverse, /i, /spp

    ; Set a custom color table and line color scheme for any tplot variable.  This allows you
    ; to use multiple color tables and/or line color schemes within a single multi-panel plot.

    ptions, var1, 'color_table', 1074
    ptions, var1, 'reverse_color_table', 1
    ptions, var1, 'line_colors', 10

    ptions, var2, 'color_table', 1078
    ptions, var2, 'reverse_color_table', 0
    ptions, var2, 'line_colors', 5

    ; Set a custom line color scheme for a tplot variable.

    ylines = get_line_colors(5, /graybkg, mycolors={ind:3, rgb:[211,0,211]})
    ptions, var1, 'line_colors', mylines

    ; Disable custom color tables and line colors for a tplot variable.

    ptions, var1, 'color_table', -1
    ptions, var1, 'line_colors', -1

    ; Set color, line style and thickness for constants.  If there are fewer colors
    ; than values, then the colors are cycled as needed.  Line styles (0-5) and line
    ; thicknesses work the same way.

    ptions, var1, 'constant',    [value0, value1, ...]
    ptions, var1, 'const_color', [color0, color1, ...]
    ptions, var1, 'const_line',  [style0, style1, ...]
    ptions, var1, 'const_thick', [thick0, thick1, ...]

    ; Plot Y-Z cuts through a tplot color spectrogram at times (X) selected with the
    ; mouse.  This example enables plotting of error bars (ERR=1), averages five
    ; neighboring measurements (NAVG=5), and sets some keywords that are passed to
    ; PLOT.  TSNAP recognizes many keywords for PLOT and WIN (or WINDOW).  See the
    ; header of tsnap.pro for more information.
    ;
    ; Use this to determine if color variations are significant.

    ey = {err:1, yrange:[1e3,1e9], ylog:1, psym:10, charsize:1.5, xsize:800, ysize:1000}
    snap, var1, key=key, navg=5

    nd ; of crib

(See general/misc/system/color_table_crib.pro)

## CWD

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:  CWD  [,newdir]
    Purpose:    Change working directory
    Keywords:
           /PICK   use dialog_pickfile to choose a directory
           PROMPT = STRING   - Changes prompt to STRING+newdir
                    The value STRING is stored in a common block variable and
                    is not required in subsequent calls to CWD
           PROMPT = 0    - Clear prompt string

    Other options:

(See general/misc/system/cwd.pro)

## GET_LINE_COLORS

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION get_line_colors
       Get the current line colors, or line colors specified by input and/or keyword.
       Returns the result as an array of 24 (3x8) RGB colors: [[R,G,B], [R,G,B], ...].
       This DOES NOT alter the color table or assert any new line colors.  To do that
       you would pass the result of this routine to line_colors, initct, or as an
       option for a tplot variable.

       To set custom line colors for any tplot panel do one of the following:

           lines = n  ; where 0 <= n <= 10
           options, varname, 'line_colors', lines

           lines = get_line_colors(line_clrs, KEYWORD=value, ...)
           options, varname, 'line_colors', lines

       To disable custom line colors for a tplot variable:

           options, varname, 'line_colors', -1

    USAGE:
       mycolors = get_line_colors([line_clrs] [, KEYWORD=value, ...])

    INPUTS:
       line_clrs : This input is optional.  Can take one of two forms:

       (1) Integer array of 24 (3x8) RGB values: [[R,G,B], [R,G,B], ...] that defines the
           first 7 colors (0-6) and the last (255).  Tplot assumes the following:

             Index           Purpose
            --------------------------------------------------
               0             black (or any dark color)
              1-6            fixed line colors
              7-254          color table (bottom_c to top_c)
              255            white (or any light color)
            --------------------------------------------------

           Indices 0 and 255 are associated with !p.background and !p.color.  For a light
           background, set !p.background = 255 and !p.color = 0.  Do the opposite for a
           dark background.  Use revvid to toggle between these options.

       (2) Integer that selects one of the predefined color schemes:

               0  : primary and secondary colors [black, magenta, blue, cyan, green, yellow, red, white]
              1-4 : four different schemes suitable for colorblind vision
               5  : same as 0, except orange replaces yellow for better contrast on white
               6  : same as 0, except gray replaces yellow for better contrast on white
               7  : see https://www.nature.com/articles/nmeth.1618, except no reddish purple
               8  : see https://www.nature.com/articles/nmeth.1618, except no yellow
               9  : same as 8 but permuted so vector defaults are blue, orange, reddish purple
              10  : Chaffin's CSV line colors, suitable for colorblind vision

       If there is no input and no keywords are set, this routine returns the current
       line colors.

    KEYWORDS:
       COLOR_NAMES: String array of 8 line color names.  You must use line color names
           recognized by spd_get_color().  RGB values for unrecognized color names are
           set to zero.  Note that named colors are approximated by the nearest RGB
           neighbors in the currently loaded color table.  This can work OK for rainbow
           color tables, but for tables that primarily encode intensity, the actual
           colors can be quite different from the requested ones.

       MYCOLORS: A structure defining up to 8 custom colors.  This provides an alternate
           method of poking individual custom colors into color indices 0-6 and 255.

                  { ind    : up to 8 integers (0-6 or 255)              , $
                    rgb    : up to 8 RGB levels [[R,G,B], [R,G,B], ...]    }

           The indicies (ind) specified in this structure will replace one or more of the
           current line colors.  You are not allowed to change color indices 7-254, because
           those are reserved for the color table.  Indices 0 and 255 allow you to define
           custom background and foreground colors.

       GRAYBKG: Set color index 255 to gray [211,211,211] instead of white.  See keyword
           MYCOLORS for a general method of setting any line color to any RGB value.
           For example, GRAYBKG=1 is equivalent to MYCOLORS={ind:255, rgb:[211,211,211]}.

           To actually use this color for the background, you must set !p.background=255
           (normally combined with !p.color=0).

       RESET: Reinitialize the predefined color schemes.

    common blocks:
       colors:      IDL color common block.  Many IDL routines rely on this.
       colors_com:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-12-31 18:28:15 -0800 (Tue, 31 Dec 2024) $
     $LastChangedRevision: 33023 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/system/get_line_colors.pro $

    Created by David Mitchell;  February 2023

(See general/misc/system/get_line_colors.pro)

## INITCT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   initct
    PURPOSE:
      Wrapper for loadct2 and loadcsv.  Calls the appropriate color table
      routine based on the requested table number:

          table numbers < 1000  (currently 0-74)      : use loadct2
          table numbers >= 1000 (currently 1000-1118) : use loadcsv

      There is substantial overlap between the standard and CSV tables:

          Standard Tables      CSV Tables       Note
        ----------------------------------------------------------------
              0 - 40           1000 - 1040      identical or nearly so
             41 - 43           1041 - 1043      different
             44 - 74           1044 - 1074      identical
               N/A             1075 - 1118      unique to CSV
        ----------------------------------------------------------------

      When tables are "nearly identical", only a few colors are different.
      The nearly identical tables are: [24, 29, 30, 38, 39, 40] <->
      [1024, 1029, 1030, 1038, 1039, 1040].  So, apart from a few slight
      differences, there are 122 unique tables.

      Keywords are provided to define fixed colors that are used for lines
      (1-6), and the background and foreground colors (0,255).
      ** Once set, these fixed colors are persistent until explicitly changed.

      Use line_colors.pro to change the fixed colors without affecting the rest
      of the color table.

      Use get_line_colors() to return a 3x8 array containing either the current
      line colors or custom colors specified by input and keyword.  This can be
      used to set custom line colors for a tplot variable.  See get_line_colors
      for details.

    USAGE:
      initct, colortbl [, KEYWORD=value, ...]

    INPUTS:
           colortbl:     Color table number.  If less than 1000, call loadct2
                         to load one of the standard color tables.  If greater
                         than or equal to 1000, call loadcsv to load one of
                         the CSV color tables.  Required.  No default.

    KEYWORDS:
           REVERSE:      If set, reverse the color table (indices 7-254).

           LINE_CLRS:    Defines custom line colors.  Can take one of two forms:

                         (1) Array of 24 (3x8) RGB values that define 8 fixed colors
                             (the first 7 and the last) of the color table:
                             LINE_CLRS = [[R,G,B], [R,G,B], ...].

                         (2) Integer that selects a predefined color scheme:

                             0  : primary and secondary colors
                            1-4 : four different schemes suitable for colorblind vision
                             5  : same as 0, except orange replaces yellow for better contrast on white
                             6  : same as 0, except gray replaces yellow for better contrast on white
                             7  : https://www.nature.com/articles/nmeth.1618 except no reddish purple
                             8  : https://www.nature.com/articles/nmeth.1618 except no yellow
                             9  : same as 8 but permuted so vector defaults are blue, orange, reddish purple
                            10  : Chaffin's CSV line colors, suitable for colorblind vision
                            11  : same as 5, except a darker green for better contrast on white

                             See get_line_colors() for RGB values of predefined schemes.
                             The most recent color schemes may not be documented here.

           COLOR_NAMES:  String array of 8 line color names.  You must use line color
                         names recognized by spd_get_color().  RGB values for unrecognized
                         color names are set to zero.  Not recommended, because named
                         colors are approximated by the nearest RGB neighbors in the
                         currently loaded color table.  This can work OK for rainbow color
                         tables, but for tables that primarily encode intensity, the
                         actual colors can be quite different from the requested ones.
                         Included for backward compatibility.

           MYCOLORS:     A structure defining up to 8 custom colors.  These are
                         fixed colors used to draw colored lines (1-6) and to define
                         the background (0) and foreground (255) colors.

                         { ind : up to 8 integers (0-6 or 255)              , $
                           rgb : up to 8 RGB levels [[R,G,B], [R,G,B], ...]    }

                         The indicies (ind) specified in MYCOLORS will replace one or
                         more of the default colors.  You are not allowed to change
                         color indices 7-254, because those are reserved for the
                         color table.  Indices 0 and 255 allow you to define custom
                         background and foreground colors.

           GRAYBKG:      Set color index 255 to gray [211,211,211] instead of white.
                         See keyword MYCOLORS for a general method of setting any line
                         color to any RGB value.  For example, GRAYBKG=1 is equivalent
                         to MYCOLORS={ind:255, rgb:[211,211,211]}.

                         To actually use this color for the background, you must set
                         !p.background=255 (normally combined with !p.color=0).
                         A quick way to do this:  revvid, /white

           PREVIOUS_CT:  Named variable to hold the previous color table number.
                         Use this to temporarily change the color table and then return
                         to the previous one.  Tplot needs this to change color tables
                         on the fly.

           PREVIOUS_REV: Named variable to hold the previous color reverse.
                         Use this to temporarily change the color table and then return
                         to the previous one.  Tplot needs this to change color tables
                         on the fly.

           SHOW:         Show the color table in a separate window after loading.

           The next three keywords are mutually exclusive.  You can only set one.  They
           are listed in order of precedence: the first one set disables the others.

           STD:          Use the standard color table file.  This is the default if
                         the environment variable IDL_CT_FILE is undefined.  This
                         keyword is used to revert to the standard file.

           SPP:          Use the Solar Probe Plus Fields color table file.  The path
                         and filename are determined automatically and stored in the
                         environment variable IDL_CT_FILE, which is used by loadct2.
                         See https://colorcet.com/index.html for a description of this
                         catalog, along with tips on how to choose a good color table.

           FILE:         The full path/filename of a color table file.  This is stored
                         in the environment variable IDL_CT_FILE, which is used by
                         loadct2.  Set this keyword to the null string ('') to revert
                         to the standard color table file.

           SUPPRESS:     Suppress floating overflow error in first call to window.

           SUCCESS:      Returns 1 if the routine finishes normally, 0 otherwise.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-02-03 13:34:12 -0800 (Mon, 03 Feb 2025) $
     $LastChangedRevision: 33110 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/system/initct.pro $

    Created by David L. Mitchell (February 2023)

(See general/misc/system/initct.pro)

## INIT_DEVICES

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  init_devices
    PURPOSE:    Initializes IDL devices for multiple systems.  Can be called from idl_startup batch file.

    KEYWORDS:
       COLORTABLE:  Colortable number to be used. (defaults to 34)

     Typical examples:

     Notes:
         Searches for the environment variable "IDL_DEVICE" and uses its value to define the
         graphics device using "SET_PLOT"

    HISTORY
     Written by Davin Larson

    $LastChangedBy: jwl $
    $LastChangedDate: 2025-08-20 11:11:05 -0700 (Wed, 20 Aug 2025) $
    $LastChangedRevision: 33563 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/system/init_devices.pro $

(See general/misc/system/init_devices.pro)

## LIBS

[Previous Routine] [Next Routine] [List of Routines]

    Name: libs
    Purpose:
      Displays location of source files.

    Usage:
      libs,string  ; string is the name of an IDL source file.
                     It may contain wildcard characters
    Restrictions:

(See general/misc/system/libs.pro)

## LINE_COLORS

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE line_colors
       Alters one or more of the fixed colors (indices 0-6 and 255) without changing
       the color table.  This includes the line colors (1-6) and the background (0)
       and foreground (255) colors.

    USAGE:
      line_colors [, line_clrs] [, KEYWORD=value, ...]

    INPUTS:
       line_clrs : Can take one of two forms:

       (1) Integer array of 24 (3x8) RGB values: [[R,G,B], [R,G,B], ...] that defines
           the first 7 colors (0-6) and the last (255).

       (2) Integer that selects a predefined color scheme:

               0  : primary and secondary colors [black, magenta, blue, cyan, green, yellow, red, white]
              1-4 : four different schemes suitable for colorblind vision
               5  : same as 0, except orange replaces yellow for better contrast on white
               6  : same as 0, except gray replaces yellow for better contrast on white
               7  : see https://www.nature.com/articles/nmeth.1618, except no reddish purple
               8  : see https://www.nature.com/articles/nmeth.1618, except no yellow
               9  : same as 8 but permuted so vector defaults are blue, orange, reddish purple
              10  : Chaffin's CSV line colors, suitable for colorblind vision
              11  : same as 5, except a darker green for better contrast on white

        If not specified, use the current (or default) line color scheme and use keywords to
        make modifications.

    KEYWORDS:
        COLOR_NAMES:  String array of 8 line color names.  You must use line color
                      names recognized by spd_get_color().  RGB values for unrecognized
                      color names are set to zero.  Not recommended, because named
                      colors are approximated by the nearest RGB neighbors in the
                      currently loaded color table.  This can work OK for rainbow color
                      tables, but for tables that primarily encode intensity, the
                      actual colors can be quite different from the requested ones.
                      Included for backward compatibility.

        MYCOLORS:     A structure defining up to 8 custom colors.  These are fixed
                      colors used to draw colored lines (1-6) and to define the
                      background (0) and foreground (255) colors.

                         { ind    : up to 8 integers (0-6 or 255)              , $
                           rgb    : up to 8 RGB levels [[R,G,B], [R,G,B], ...]    }

                      The indicies (ind) specified in MYCOLORS will replace one or
                      more of the default colors.  You are not allowed to change
                      color indices 7-254, because those are reserved for the
                      color table.  Indices 0 and 255 allow you to define custom
                      background and foreground colors.  For example, the following
                      chooses color scheme 5, but sets the background color to light
                      gray with a black foreground (pen) color:

                         line_colors, 5, mycolors={ind:255, rgb:[211,211,211]}
                         !p.color = 0
                         !p.background = 255

        GRAYBKG:      Set color index 255 to gray [211,211,211] instead of white.
                      See keyword MYCOLORS for a general method of setting any line
                      color to any RGB value.  For example, GRAYBKG=1 is equivalent
                      to MYCOLORS={ind:255, rgb:[211,211,211]}.

                      To actually use this color for the background, you must set
                      !p.background=255 (normally combined with !p.color=0).

        PREVIOUS_LINES: Named variable to hold the previous line colors.
                      Tplot needs this to swap line colors on the fly.

           SUCCESS:   Returns 1 if the routine finishes normally, 0 otherwise.

    SEE ALSO:
        get_line_colors() : Works like this routine, but returns a 24 element array
                      instead of asserting the new line colors.  Allows you to define
                      a custom set of line colors in a format that you can use as an
                      option for a tplot variable.
        initct :      Loads a color table without changing the line colors, except by
                      keyword.

    common blocks:
       colors:      IDL color common block.  Many IDL routines rely on this.
       colors_com:

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-01-28 08:52:54 -0800 (Tue, 28 Jan 2025) $
     $LastChangedRevision: 33098 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/system/line_colors.pro $

    Created by David Mitchell;  February 2023

(See general/misc/system/line_colors.pro)

## LOADCT2

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE loadct2, colortable
       By default LOADCT2 uses the same color table used by LOADCT
       This can be changed in 3 ways:
       1) Use the FILE keyword to define a new file
       2) Define the environment variable IDL_CT_FILE to point to a new file
       3) Place a new color table file in the same directory as LOADCT2 that matches
             the name: 'colors*.tbl'.  (The last file found with file_search is used).

       This routine now uses get_line_colors() to define the eight fixed RGB colors for
       drawing lines and setting the background and foreground colors.  All line color
       keywords work as before but are now passed to that function.  Please place any
       new line color schemes in get_line_colors().

    USAGE:
       loadct2, colortable [, KEYWORD=value, ...]

    INPUTS:
       colortable: Color table number.  Required.

    KEYWORDS:
       REVERSE: If set, then reverse the table order from bottom_c to top_c.
       PREVIOUS_CT: Needed by tplot to change color tables on the fly.
       PREVIOUS_REV: Needed by tplot to change color tables on the fly.
       FILE:  (string) Color table file
              If FILE is not provided then LOADCT2
              Uses the environment variable IDL_CT_FILE to determine
              the color table file if FILE is not set.
       LINE_CLRS: Integer array of 24 (3x8) RGB values: [[R,G,B], [R,G,B], ...]
              If this input does not have exactly 24 elements, then a predefined set of 8 colors
              will be used based on the value of the first element.  Pre-defined color schemes
              are currently (see code below for any new undocumented schemes):
                 0  : primary colors
                1-4 : four different schemes suitable for colorblind vision
                 5  : primary colors, except orange replaces yellow for better contrast on white
                 6  : primary colors, except gray replaces yellow for better contrast on white
                 7  : see https://www.nature.com/articles/nmeth.1618 except no reddish purple
                 8  : see https://www.nature.com/articles/nmeth.1618 except no yellow
                 9  : same as 8 but permuted so vector defaults are blue, orange, reddish purple
                10  : Chaffin's CSV line colors, suitable for colorblind vision
       LINE_COLOR_NAMES:  String array of 8 line color names.  You must use line color names
              recognized by spd_get_color().  RGB values for unrecognized color names are set
              to zero.  Note that named colors are approximated by the nearest RGB neighbors in
              the currently loaded color table.  This can work OK for rainbow color tables, but
              for tables that primarily encode intensity, the actual colors can be quite different
              from the requested ones.  Included for backward compatibility.
       COLOR_NAMES: Synonym for LINE_COLOR_NAMES.  Allows better keyword minimum matching, if the
              previous keyword can be retired.  Both keywords are accepted - this one takes precedence.
       MYCOLORS:
              A structure defining up to 8 custom colors.  This provides an alternate method of
              poking individual custom colors into the fixed color indices (0-6 and 255).

                { ind  : up to 8 integers (0-6 or 255)              , $
                  rgb  : up to 8 RGB levels [[R,G,B], [R,G,B], ...]    }

              You can also specify LINE_CLRS and LINE_COLOR_NAMES, and this keyword can make further
              adjustments.

              The indicies (ind) specified in MYCOLORS will replace one or more of these
              colors.  You are not allowed to change color indices 7-254, because those
              are reserved for the color table.  Indices 0 and 255 allow you to define
              custom foreground and background colors.
       GRAYBKG: Set color index 255 to gray [211,211,211] instead of white.
              See keyword MYCOLORS for a general method of setting any line color to any RGB value.
              For example, GRAYBKG=1 is equivalent to MYCOLORS={ind:255, rgb:[211,211,211]}.
              To actually use this color for the background, you must set !p.background=255
              (normally combined with !p.color=0).
       RGB_TABLE: Named variable that returns the color table as a 256x3 array of RGB values

    common blocks:
       colors:      IDL color common block.  Many IDL routines rely on this.
       colors_com:
    See also:
       "get_colors","colors_com","bytescale","get_line_colors","line_colors","showct","initct"

     $LastChangedBy: jwl $
     $LastChangedDate: 2025-08-20 11:11:05 -0700 (Wed, 20 Aug 2025) $
     $LastChangedRevision: 33563 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/system/loadct2.pro $

    Created by Davin Larson;  August 1996

(See general/misc/system/loadct2.pro)

## SHOWCT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE showct
       Show the specified color table and line colors in a new window.  Does not
       alter the current color table.  Can also show a catalog of color tables.

    USAGE:
       showct [, n] [, KEYWORD=value, ...]

    INPUTS:
       n:         Color table number.  Standard tables have n < 1000.  CSV tables
                  have n >= 1000.  See 'initct' for details.  If n is not provided,
                  show the current color table.

    KEYWORDS:
       REVERSE:   If set, then reverse the table order from bottom_c to top_c.

       LINE_CLRS: Show an alternate line scheme.  See line_colors.pro.

       COLOR_NAMES: Names of custom line colors.  See line_colors.pro.

       MYCOLORS:  Structure of custom line colors.  See line_colors.pro.

       GRAYBKG:   Set background color to gray.  See line_colors.pro.  For this to
                  work properly, !p.background must be set to 255 (see keyword
                  WHITE below, or see color_table_crib.pro).

       INTENSITY: Show intensity in a separate window.

       KEY:       Structure of win options.  Window dimensions of 600x600
                  cannot be overridden.

       CNUM:      Returns the window number chosen for the color table plot.

       TNUM:      Returns the window number chosen for the intensity plot.

       RESET:     Forgets any window numbers.

       CATALOG:   Show a catalog of available color tables as a grid of color bars,
                  with the table number below each bar.  Color bars are shown for
                  the current catalog, unless you choose a different one with of
                  the following four keywords.

       STD:       Use the standard (n < 1000) or csv (n >= 1000) color tables for
                  both the catalog and the table number specified by n.  This is
                  equivalent to FILE=''.

       SPP:       Use the SPP Fields color tables for both the catalog and the table
                  number specified by n.

       FILE:      Use the color table defined by this file (full path and filename)
                  for both the catalog and the table number specified by n.  Set
                  this keyword to the null string ('') to use the standard (n < 1000)
                  or csv (n >= 1000) tables.

       BLACK:     Temporarily use a black background.  Default is !p.background.

       WHITE:     Temporarily use a white background.  Default is !p.background.
                  (This keyword is ignored if BLACK is set.)

    SEE ALSO:
       xpalette:  Shows the current color table in an interactive widget.  Provides
                  more functionality, but only for the current color table.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-02-03 13:34:12 -0800 (Mon, 03 Feb 2025) $
     $LastChangedRevision: 33110 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/system/showct.pro $

(See general/misc/system/showct.pro)

## THMCTPATH

[Previous Routine] [List of Routines]

    NAME: thmctpath

    PURPOSE:
       Gets the path of the color table used by themis

    CALLING SEQUENCE:
      thmctpath,getpath

    $LastChangedBy: pcruce $
    $LastChangedDate: 2009-06-10 09:57:19 -0700 (Wed, 10 Jun 2009) $
    $LastChangedRevision: 6105 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/system/thmctpath.pro $

(See general/misc/system/thmctpath.pro)