NOCS ORCA1 home page

The NOCS ORCA1 home page

     

imagenemo - image generator for horizontal slices

Currently available on: Linux boxes, nautilus and postproc

source /working/jrd/occam/HDF5/oc5setup to set up the appropriate environment

imagenemo reads horizontal slices of ocean model data and produces a bitmap image of the data according to the controls imposed by the command-line arguments. These arguments provide a fair degree of control over the final image including:

imagenemo is built using the ImageMagick library which provides routines to manipulate images in a multitude of image formats. imagenemo restricts output to high quality jpegs. In order to access font information (for annotations) imagenemo needs to have access to an X server. This means the command must be run in a desktop environment where a valid X display is accessible. If "xclock" works then so will imagenemo. Despite this minor restriction imagenemo is ideally suited for incorporation into scripts thus automating the production of frames for animation.

Imagenemo is a specially configured version of the OCCAM utility: h5toglobal (see: its description here). The original utility worked with OCCAM-style HDF5 datasets and combined data from the two separate model grids onto a single image. Imagenemo will work from a single NetCDF file but the NEMO files do not generally contain the masking fields. Thus to overlay a meaningful land mask the model bathymetry dataset must also be supplied. This is normally called "bathy_level.nc" but each model configuration will have its own dataset. Imagenemo is compiled with a default path to one version of this file but this may be ignored by either:

setenv NEMOBATHYFILE /scratch/occam/TRYSVN/NOC_NEMO/bathy_level.nc

All other options are controlled via an array of command-line arguments. For fancier images the list can get quite long and not particularly memorable. Fortunately, imagenemo will record the invoking command within the image as a jpeg comment field. Thus the creation command for any image can be retrieved using the standard jpeg utility: rdjpgcom image.jpg

The full set of command line arguments is:

Usage: imagenemo 
                  -f infile 
                  -o outimage 
                  -d dataset_name 
                  [-sw bottom_left_degrees bottom_left_degrees] {0.0 -80.0} 
                  [-ne top_right_degrees top_right_degrees] {360.0 90.} 
                  [-k k_level] {0}
                  [-limits data_min data_max] {-1.9 30.}
                  [-r i_size j_size] {720 400}
                  [-high] {1200 652}
                  [-medium] {720 400}
                  [-low] {360 200}
                  [-video] {1024 576}
                  [-logsc]
                  [-cs colour_file] {pastel.pal} 
                  [-overd overlay_dataset_name] 
                  [-overf filename_containing_overlay_dataset]
                  [-overk overlay_k_level] {0} 
                  [-olimits overlay_data_min overlay_data_max] {0.0 180.0}
                  [-overi overlay_threshold_index] {2} 
                  [-overcs overlay_colour_file] {grey.pal} 
                  [-cenl centreline_longitude] {300.0} 
                  [-no_offset] 
                  [-png]
                  [-moll] 
                    [-mcen centre_meridian] {300} 
                  [-ortho] 
                    [-eu1 first_Euler_angle] {90.0} 
                    [-eu2 second_Euler_angle] {90.0} 
                    [-eu3 third_Euler_angle] {180.0} 
                    [-ta offset_translation_angle] {0} 
                    [-td offset_translation_distance] {0} 
                    [-gsize globe_scale_factor] {80} 
                    [-vdist viewpoint_distance] {10} 
                  [-icosa]
                  [-conic]
                    [-mcen longitude of rotated pole] {300}
                    [-mlat latitude of rotated pole] {90}
                  [-whitebg] 
                  [-blackbg]
                  [-datec] 
                  [-dplace clock_radius ck_xpos ck_ypos datestr] 
                  [-logo] 
                    [-lsize logo_width {150} {100} {50}] 
                    [-lpos logo_xpos logo_ypos {1000,150} {600,100} {300,50}] 
                    [-lbg white|black|grey] 
                  [-annotate xpos ypos label_text] 
                  [-title alternative_title_text]
                  [-aset alternative_txt_and_bg_set]
                  [-usex]
                  [-vscale] 
                  [-nomask] 
                  [-noscale] 
                  [-bcoord]
                  [-usemap]
                  [-savemap]
                   [-mapf transform_mapping_file {mapfile.unf}] 
                  [-nooverl]
                  [-nctime netcdf_time_level] 
                  [-combod 2nd_component_dataset ] 
                    [-combof infile2] 
                    [ -uv ] 
                    [-sum ]
                    [ -diff ] 
                    [ -interp interpolation_factor ] 
                      [ -frame_start 1st_frame_number ] 
                    [-nscombo ]
                  [-chscale output_colourscale_image_file]
                  [-cvscale output_colourscale_image_file]
                  [-crescale scale_factor_for_colourscale]
                  [-corescale scale_factor_for_overlay_colourscale]
                  [-box]
                  [-usemax]
                  [-usemin]
                  [-show] 
                  [-verbose] 

Formally, only the first three are essential (as indicated by [] brackets) but the built-in defaults (shown in {}) are only relevant to global images of the SST. Thus in practise many more of the optional arguments are required. Each is explained in the following sections which include examples for illustration:

-f infile
An input NetCDF file name must be supplied.
-o outimage
An output image filename must be supplied.
-d dataset_name
The "short name" of the dataset to be extracted and displayed. Names containing spaces must be quoted; e.g. "POTENTIAL TEMPERATURE (MEAN)".
[-sw bottom_left_degrees bottom_left_degrees] {0.0 -80.0}
Optional restriction on the region to be displayed. The SW corner of the viewing window should be supplied in degrees E, degrees N.
[-ne top_right_degrees top_right_degrees] {360.0 90.}
Optional restriction on the region to be displayed. The NW corner of the viewing window should be supplied in degrees E, degrees N. Longitudinal values greater than 360. are permitted to allow regions which straddle the GM
[-k k_level] {0}
The level to be extracted from a 3D dataset. This value should be 0 for 2D datasets.
[-limits data_min data_max] {-1.9 30.}
The data limits over which the 252 colours of the colour scale are applied. Values less than the minimum will be assigned the first colour in the scale. Values greater than the maximum will be assigned the last colour in the scale.
[-r i_size j_size] {720 400}
The image size in pixels. Note that the default horizontal colourscale legend will be placed in an additional stripe at the bottom of the image. The height of this additional area will be 15% of the supplied height. The (optional) vertical colour scale will occupy the left-hand 15% of the width and will overlay the underlying image.
[-high] {1200 652}
Predefined image size giving a fullscreen resolution image.
[-medium] {720 400}
Predefined image size giving a reasonable image suitable for animations
[-low] {360 200}
Predefined image size giving a small, low resolution image suitable for previewing or web use.
[-video] {1024 576}
Predefined image size giving a PAL resolution widescreen format image.
[-logsc]
Use the log (base 10) of the main variable for plotting. Range limits supplied to the -limits option should be limits for the log values. Currently only the main field (either direct values or combined via the -combo options) can be treated. Overlay fields (supplied via the -over options) are not affected by this option.
[-cs colour_file] {pastel.pal}
The name of the colourscale to use. Current options are: pastel.pal, pastel2.pal, ps.pal, seaice.pal, best64.pal, blue2red_b.pal, blue2red.pal, brown2green.pal, brown2green_desat.pal, brown2white.pal, tim.pal, blue2white.pal, relief.pal, bathy.pal, velocity.pal
[-overd overlay_dataset_name]
Optionally a second dataset may be overlaid on the first. The mechanism is crude and happens in pixelspace but it can be used to overlay fields which overlap only in confined areas. The most useful examples of these are the seaice fields. The named dataset must be present in the original input files.
[-overf filename_containing_overlay_dataset]
Optionally a second filename can be supplied indicating where the overlaid dataset is to be read from. The default assumption is that the overlaid data are in the main datafile (-f).
[-overk overlay_k_level] {0}
The k-level to be extracted
[-olimits overlay_data_min overlay_data_max] {0.0 180.0}
The data range limits for the overlaid field
[-overi overlay_threshold_index] {2}
The threshold colour index. Only pixels in the overlay image with a colour index greater than this value will be mapped onto the combined image. Thus the degree of masking achieved by the overlay field is controlled by the combination of the overlay data limits and the overlay threshold index.
[-overcs overlay_colour_file] {grey.pal}
The colour file applied to the overlay field (monochromatic scales work best)
[-cenl centreline_longitude] {300.0}
The longitude of the centre of the image. This is really only relevant to global regions which can be treated cyclically. Strange effects can happen if you fail to switch this off (-no_offset) with subglobal images.
[-no_offset]
Switch of the centreline positioning which assumes the image can be treated cyclically. This is applied automatically for Mollweide and orthographic projections.
[-png]
Force output image format to be PNG instead of JPEG. This happens automatically if the output filename ends with a .png extension. PNG format is lossless, compact and supports transparency.
[-moll]
Apply a Mollweide projection.
[-mcen centre_meridian] {300}
Set the longitude (degrees E) of the meridian running down the centre of the Mollweide ellipse.
[-ortho]
Apply an orthographic projection. Essentially a "gplot" emulator without the interactivity. For anyone familiar with gplot the next 7 options are the same view controls that are set in gplot's preview window. Everyone else will soon get the hang of it!
[-eu1 first_Euler_angle] {90.0}
E-W rotate in degrees E
[-eu2 second_Euler_angle] {90.0}
N-S rotate in degrees N
[-eu3 third_Euler_angle] {180.0}
Tilt angle in degrees
[-ta offset_translation_angle] {0}
Offset translation angle in degrees (only useful if you need to move the globe from the centre of the image)
[-td offset_translation_distance] {0}
Offset translation distance (in globe radii) (only useful if you need to move the globe from the centre of the image)
[-gsize globe_scale_factor] {80}
Globe scale factor. Decrease to zoom in; increase to zoom out
[-vdist viewpoint_distance] {10}
Viewpoint distance. Decrease to zoom in; increase to zoom out
[-icosa]
Map a global image onto the faces of an icosahedron. The resulting image can be cut-out, folded and glued to form a 3-dimensional solid.
[-conic]
An attempt to mimic the transformations necessary for a spherical display device. Only partially successful and still under development.
[-mcen longitude of rotated pole] {300}
longitude of the central point in the conic projection
[-mlat latitude of rotated pole] {90}
latitude of the central point in the conic projection
[-whitebg]
Force a white background. The default background is grey which is better for animation purposes. White is preferred for hardcopies. Only really relevant for Mollweide or orthographic projections since the default projection fills the image anyway
[-blackbg]
Force a black background.
[-datec]
Show a date clock in the bottom lefthand corner (assuming a date string is obtainable from the input file). This was an OCCAM option, with NEMO an easily accessible datestring is not available. For now it has to be manually provided with the -dplace option. Thus -datec and -dplace are both required to activate a date clock.
[-dplace clock_radius ck_xpos ck_ypos datestr]
Manually set the date clock radius and position (pixel coordinates). NEMO requires a 4th argument which is an eight character date string of the form YYYYMMDD. In scripts, this string can be provided by the nocstfinder utility. Automatic placement equates to settings of: {60 1070 522}, {36 608 288} and {18 304 144} for the high, medium and low preset sizes respectively.
[-logo]
Apply the OC1, OC4 or OC12 logo as determined by the size and placement options (Hmm not particularly useful for NEMO plots. This will be replaced with a more appropriate set of logos once the project has some.)
[-lsize logo_width {150} {100} {50}]
The pixel width of the logo. The defaults shown are the default widths for the high, medium and low preset image sizes. Other image sizes will default to the settings for high
[-lpos logo_xpos logo_ypos {1000,150} {600,100} {300,50}]
Pixel coordinates of the bottom lefthand corner of the logo. Pixel coordinates run left to right, top to bottom from the top lefthand corner.
[-lbg white or black or grey]
Select background colour of the logo. Due to difficulties in handling transparency, it is necessary for the logos to be supplied with three different background colours (the background here refers to the corners between the ellipse edges and the bounding box. The program trys to make a sensible choice of which one to include but this option provides a method for the user to override the automatic choice.
[-annotate xpos ypos label_text]
Add an optional line of annotation starting at the supplied pixel coordinates.
[-title alternative_title_text]
The default plot title is constructed from the variable name and combination operation (if applicible). This option allows the user to provide alternative text of their own choosing.
[-aset alternative_txt_and_bg_set ]
An occasionally useful option to provide larger, white-filled text. There is only limited control over text properties within imagenemo. Text is scaled to a limited degree with image size but the sizes may not be appropriate for very large or very small images. In extreme cases it is up to the user to add appropriately sized (and coloured text) afterwards. The ImageMagick utilities (such as mogrify) provide versatile options for doing this with the -draw option.
[-usex]
Imagenemo attempts to use PostScript fonts by default. This allows the utility to be used in batch mode without access to an X server. However it may be quicker and easier to force the use of X server fonts. This option forces the program to use X server fonts exclusively.
[-vscale]
Apply a vertical colour scale (positioned to the lefthand side) rather than the default horizontal scale at the bottom. This is most relevant to Mollweide or orthographic projection images.
[-noscale]
Switch off colour scale legend and default annotations (explicit annotations requested via the -annotate flag will still be applied).
[-bcoord]
This switch forces any coordinate fields in the variable's data file to be ignored and to read and use those in the bathymetry file instead. Useful if the coordinates are missing or corrupt in the main input file.
[-savemap]
For large images and/or high resolution source data, the time taken to compute the pixel to model coordinate mapping is a significant part of the overall processing time. This option writes the mapping data to an unformatted binary file (mapfile.unf). Subsequent calls to imagenemo with the same image parameters can optionally use this map file (see -usemap) to speed up processing time. Very useful for producing animation sequences where only the input field varies. This option is ignored if the mapping file already exists.
[-usemap]
Read and apply an existing mapping between pixels and model points. See -savemap option for details. This option has no effect if the mapping file does not exist.
[-mapf map_file_name] {mapfile.unf}
An optional filename for the mapping data to be either created (savemap option) or used (usemap option). If not supplied the default name of mapfile.unf will be used.
[-nooverl]
Imagenemo was originally designed to work with full NEMO datasets and includes special treatment of the cyclic columns. Some Met Office NEMO files have had the cyclic columns and north-fold row removed. This option reinstates the missing columns and rows so that the internal logic will work. If your images have a black vertical line through the Indian Ocean then you probably need to activate this option.
[-nctime netcdf_time_level]
This option provides the time-level which is to be extracted from a 4 dimensional dataset in a netcdf file.
[-combod 2nd_component dataset]
An optional 2nd compoent dataset which can be combined with the first component dataset to produce either: a sum, difference (1st - 2nd) or a speed (sqrt(1st^2 + 2nd^2)) field. Alternatively, the 2nd component field can be used as the end member in a linear interpolation exercise that produces extra animation frames between the 1st and 2nd component fields, see the -interp option for a description.
[-combof infile]
An optional input file name giving the location of a 2nd component dataset. If -combod is used without this option then the 1st component datafile is assumed to also contain the 2nd component.
[-uv]
Combine the 2 components as a speed field (sqrt(1st^2 + 2nd^2)). This one works best with the -logsc option.
[-sum]
Calculate and plot the sum of the 2 components.
[-diff]
Combine the 2 components as a difference field (1st - 2nd).
[-interp interpolation_factor]
Use the 1st and 2nd components as a end members in a linear interpolation exercise to produce additional frames between the two sets. The number of additional frames produced is determined by the interpolation factor which should be 0 < fac < 1. For example, if a and b are the 1st and 2nd component fields respectively, then a factor of 0.2 will produce 5 frames using the algorithm: (1-t)*a + t*b, where t= 0.0, 0.2, 0.4, 0.6 and 0.8. The images will be placed in files named according to the -o option but with a four-digit frame-number extension. By default, the frame numbers will start at 1 but this may be altered by the -frame_start option.
[-frame_start 1st_frame_number]
Use the supplied integer value as the first frame number in a interpolated sequence. This number will be incremented by one for subsequent frames.
[-nscombo]
Combine the 2 components as a North-South hemisphere composite. The 1st field is plotted in the Northern hemisphere and the 2nd in the Southern hemisphere.
[-chscale output_colourscale_image_file]
produce a horizontal colourscale image separately in the named file.
[-cvscale output_colourscale_image_file]
produce a vertical colourscale image separately in the named file.
[-crescale scale_factor_for_colourscale]
use the supplied scale factor to rescale the units displayed on the main colourscale.
[-corescale scale_factor_for_colourscale]
use the supplied scale factor to rescale the units displayed on the colourscale for the overlaid field.
[-usemax]
Scan the data field to find the maximum value and use this as an upper limit (main variable only).
[-usemin]
Scan the data field to find the minimum value and use this as a lower limit (main variable only).
[-show]
Optionally display the final image on the screen as well as writing to the output file. < ctrl > Q can be used to close the image.
[-verbose]
Mainly for observing progress whilst debugging.
Here are some examples with the resultant images:
imagenemo -f coordinates.nc -o basicview.jpg -d e2t  -limits 0.0 112000. -r 500 300 -show
basicview.jpg
imagenemo -f coordinates.nc -o try.jpg -d e2t -limits 0.0 112000. -r 500 300 -show -ortho -vscale -datec -eu2 40.
fancierview.jpg
imagenemo -f coordinates.nc -o try.jpg -d e2t -limits 0.0 112000. -r 500 300 -show -moll
mollweide.jpg

A more interesting example that uses many options (click on the thumbnail image to obtain the full-size image):

imagenemo -savemap -mapf flatglobal_1024x512.mapf \
          -f $MEAN_DIR/1987/ORCA0083-N01_19871231d05U.nc \
          -o ./globaluv.jpg -k 24 \
          -d vozocrtx \
          -combof $MEAN_DIR/1987/ORCA0083-N01_19871231d05V.nc \
          -combod vomecrty \
          -uv \
          -logsc \
          -limits -1.25 0.0 \
          -nctime 1 \
          -bcoords \
          -sw 0.0 -90. -ne 360. 90. \
          -no_offset \
          -r 1024 512 \
          -noscale \
          -cs blue2white.pal
 

Finally a composite that illustrates the available palettes: