NCPLOT.DAT

Basic Information

File-Type

ncplot.dat

File-Form

FORMATTED

Version

March 2022

Description-Date

April 2022

Significance of the File

contains general steering data for the program NCPLOT.

File-Contents (in Catchwords)

Block "Program_Parameters"

The block Program_Parameters contains general steering data.

• Key "Language" : Language preference for labels and texts:

• DE = German,
• EN = English.

• Key "Max_Read_Storage" : max. read only memory (in bytes) for analysis
• Key "Min_Water_Depth" : minimum water coverage in [m].

Hint:
The excluding of data from the presentation in case of low water coverage is only possible, if the variable to be displayed points in a certain way to a variable associated with the total water depth.
The CF-NetCDF output of UnTRIM programs fulfills this requirement.
The page NCPLOT: Min_Water_Depth illustrates the effect of this control parameter.

• (optional) Key "Infobox_Plot_Area" : Image area for the metadata infobox.

If this image area is specified, information about the plot creation will be given to the graphic. This includes information about the underlying data files as well as if neccessary information about used data filtering.

• (optional) Key "PLR_Representation" : Default setting for line symbols of data curves in line charts.
• (optional) Key "PMR_Representation" : Default setting for marker symbols of data curves in line charts.
• (optional) Key "PLR_Palette" : Color palette and start color for line symbols of data curves in line charts.
• (optional) Key "PMR_Palette" : Color palette and start color for marker symbols of data curves in line charts.
• (optional) Key "Picture_Name_Fixum" : fixed name part for graphic file(s).
• (optional) Key "Phydef_Units" : Display physical units as in PHYDEF administration.

Hint: Without explicit request, the units are displayed according to the BAW Rules.

• (optional) Key "Output_Format" : Output format for the generated graphics (CGM or SVG).

Block "SVG_Specifications"

Optional block with attributes for graphic output in SVG format.

• (optional) Key "SVG_Maximum_Size" : Maximum size of the SVG graphic, i.e. factor for converting NDC space from GKS to SVG space.
• (optional) Key "SVG_Font_Family" : Font family for text elements.
• (optional) Key "SVG_Free_Text_Attributes" : Font attribute(s) that are given to ALL texts of the SVG graphic.
• (optional) Key "SVG_Axis_Text_by_Char" : Write texts on diagram axes character by character (as in CGM format).
• (optional) Key "SVG_Legend_Box_by_Char" : Write legend texts of line charts character by character (as in CGM format).

Block "Dataset"

Description of a data set to be displayed.

For addressing the data to be displayed, either the Start-Step-Stride technique or the DimSelect method is available. The user has to choose one way or the other, the procedures exclude each other. Each Start-Step-Stride-Addressing can be copied by DimSelect, the other way round that is not the case. DimSelect offers additional options for data selection, with the method you can also realize non-equidistant index selection.

Start-Step-Stride technique

For each dimension of the variable a start, step and stride value must be specified.
The page NCPLOT: Define DataSet gives instructions for addressing the desired data.

DimSelect method

DimSelect also requires the addressing of the indices for each dimension of the data variables to be displayed. But this can also happen indirectly. Various suitable selection methods are provided. The user can, for example, choose all faces by DimSelect_All without knowing the specific number, or pass the program via DimSelect_Various_Date a selection of times to be displayed. It is the responsibility of the program to find the corresponding indices.
Related to data curves of line charts the DimSelect method offers a further advantage: For the individual dimensions this mimic allows to create text components for the names of the data series shown in the curve legend.

Control file can contain multiple blocks of this type.

• Key "Name" : unique name of this data set.
• Key "File" : name of the CF-NetCDF file (*.nc) with the data to be displayed.
• Key "Variable" : Description of the data whose values are to be displayed.

• Parameter 1 = name of the variable (in file of type *.nc)
• (optional) Parameter 2 = role of the variable as part of a vector

• X-component = Variable is the X component of a vector
• Y-component = Variable is the Y component of a vector
• normal_component = Variable is the normal component of a vector

Hint: The command "ncdump -h <filename>.nc" shows the header of the CF-NetCDF file. The names of the offered variables and their dimensions can be found in the metadata.

• (optional) Key "Start" : start address for the data to be displayed.
• (optional) Key "Step" : number of steps for the data to be displayed.
• (optional) Key "Stride" : increment for the data to be displayed.
• (optional) Key "DimSelect_EquiDist_Index" : Equidistant selection of indices for a given dimension.
  Exemplary:

• Parameter 1 = Name of the dimension
• Parameter 2 = NONE or text component for curve legend
• Parameter 3 = Index becomes part of the curve legend .true./.false.
• Parameter 4 = Start Index
• Parameter 5 = Index increment
• Parameter 6 = Number of steps

• (optional) Key "DimSelect_EquiDist_Date" : Equidistant selection of times.
• (optional) Key "DimSelect_StartEnd_Index" : Selection of all indices from start to end index.
• (optional) Key "DimSelect_StartEnd_Date" : Selection of all times from start to end date.
• (optional) Key "DimSelect_Single_Index" : Selection of a specific index.
• (optional) Key "DimSelect_Single_Date" : Selection of a specific date.
• (optional) Key "DimSelect_Various_Index" : List of various indices.
• (optional) Key "DimSelect_Various_Date" : List of various dates.
• (optional) Key "DimSelect_All" : Selection of all indices of a dimension.
• (optional) Key "DimSelect_ByLabel_LabVar" : Determine indices with list of names by label variable.
• (optional) Key "DimSelect_ByLabel_List" : Continuation line to Key DimSelect_ByLabel_LabVar.
• (optional) Key "DimSelect_Location_Coord" : Selection of locations by coordinates.
• (optional) Key "DimSelect_LocByFile_File" : Selection of locations from file with locations.
• (optional) Key "DimSelect_LocByFile_List" : Continuation line to Key DimSelect_LocByFile_File.
• (optional) Key "Dimensions_for_Picture_Series" : Requesting seperate presentations for selected dimensions.

Hint:
Causes series of pictures, i.e. for each selected index of the dimensions listed here a separate picture is created.
Only works with line charts.
Picture series must be the same length!

Block "Layer"

A block of type Layer defines a area diagram. The illustration in the horizontal plane (the map view) differs fundamentally from the area charts with axes.
Control file can contain multiple blocks of this type.

• Key "Name" : unique name of this layer and the possibility of assigning a different plot level to the diagram.
• Key "Layer_Dataset_Name" : name of the dataset to be displayed. Or a valid connexion (OPERATOR string) made out of known data sets, e. g. [DSet2-DSet1]/[DSet1+DSet2], ABS[DSet], SQR[DSet] or G18[DSet]. Constant factors in arithmetic operation possible.
• Key "Layer_Type" : type of data view of this layer.

• XY_data = Map, or top view illustration (horizontal plane)
• PZ = Vertical section along profile (3D data)
• TZ = Time depth diagram (3D data)
• PT = Hovmöller diagram variant 1: X-axis=profile axis (P), Y-axis=time axis (T).
• TP = Hovmöller diagram variant 2: X-axis=time axis (T), Y-axis=profile axis (P).

• Key "Layer_Primitive_Name" : graphic primitive to visualize the data in the layer.

• Parameter 1 = Symbolization of the layer

• GPM = as poly marker
• GPL = as poly line (only Layer_Type XY_data)
• GFA = as fill area
• GTX = as text
• VEC = as vector (only Layer_Type XY_data)

• (optional) Parameter 2 = Type of the vector
  ... optional parameter, only at VEC visualization permitted.
  ...allows, for example, the interpolation of the total vector from the normal component a vectorial quantity.

• total = total vector
• normal = normal vector

• Key "Layer_Primitive_Representation_Name" : name of the representation of the primitive.
• Key "Layer_Bounds_Name" : name of the interval definition for this layer (from the file bounds.cfg.dat).

Hint: The number of intervals in the interval definition and the number of colors of the associated color legend must match.

• Key "Layer_Palette_Name" : name of the color legend for this layer (corresponds to the attribute Name in the file palette.dat. More detailed information about palettes on file description page palettes.cfg.dat).
• Key "Layer_Invert_Palette" : invertation of the color ramp.
• (optional) Key "Layer_Normalization_Transformation_Name" : name of the normalization transformation for this layer.

Hint: Required for diagram definition map view (Layer_Type XY_data).

• (optional) Key "Layer_Area" : Image area spanned by the diagram axes.

Hint: Required for definitions of diagrams working with axes.

• (optional) Key "Layer_Extent" : Total area that the diagram in the picture takes up.

Hint: Required for definitions of diagrams working with axes.

• (optional) Key "Layer_X-Axis" : X-axis of the diagram and its positioning.

Hint: Required for definitions of diagrams working with axes.

• (optional) Key "Layer_Y-Axis" : Y-axis of the diagram and its positioning.

Hint: Required for definitions of diagrams working with axes.

• (optional) Key "Layer_Legend_Plot_Area" : image area for the color legend of this layer. Depending on the space, the color legend can be applied horizontally or vertically.
• (optional) Key "Layer_Legend_Label_Switch" : Switch list for switching off or positioning labels of the color legend.
• (optional) Key "Layer_Data_Description_Name" : name of the Data_Description text box, which should collects up the data description (e.g. indication of the time) of this layer.
• (optional) Key "Layer_Display_Units" : physical unit in which the data should be converted for the graphical presentation.

Hints:
The original unit of the data and the target unit must be known in the configuration file phydef.cfg.si.dat. In addition, the SI-base (dimension) of the units must be identical.

• (optional) Key "Layer_Display_Name" : name of physical quantity, will be used instead of the original name given in the input data set. Without this line the name in PHYDEF is used, if the variable owns the attribute name_id..
  Dynamic text parts can be realized with special placeholders:

• <LAY_DSET> will be replaced by the name of the dataset associated with the layer.
• <LAY_DIM1> will be replaced by the info text for the 1st dimension of the displayed data set.
• <LAY_DIM2> will be replaced by the info text for the 2nd dimension of the displayed data set.
• <LAY_DIM?> etc. to the number of data set dimensions.

• (optional) Key "Layer_Vector_Legend_Plot_Area" : image area for the vector legend in case of arrows with length_type proportional.
• (optional) Key "Layer_Vector_Thinout_Raster" : dimensions of the grid used to thin out the display of vector arrows.
• (optional) Key "Layer_NOBS_Filter" : filter for displayed data based on ancillary variable with type number of observations:
  • parameter 1: filter type:
    • EQ = display data only for a fixed number of observations;
    • LE = display data for a certain number of observations or less;
    • LE = display data for a certain number of observations or more.
  • parameter 2: filter value:
    • 0 = maximum number of observations;
    • N = specified number of observations;
    • -M = maximum number of observations minus M.
• (optional) Key "Layer_Description_Textbox" : name of a textbox to be linked with the layer.
• (optional) Key "Layer_Route_Dataset" : name of a dataset with profile route for sorting and filtering data to be displayed.
• (optional) Key "Layer_Legend_Number_Format" : Format specification for numerical values of the color legend.
• (optional) Key "Layer_ASCII_Output" : Write data displayed in layer to text file.

Block "Normalization_Transformation (NTN)"

Definition of an image section and description of the link between the world and image coordinates.
A block of this type is only required for areal representation in the horizontal plane (layer definition with Type == XY_Data).
The coordinates of the drawing area, the so-called NDC space, range from [0.0,0.0] to [1.0,1.0]. For an undistorted view of the area the representation scale in the X direction must match the scale in Y-direction (DWC / DNDC = const); optionally also key "Autoscale" can be used for this purpose. Distorted representations are also possible.

• Key "Name" : unique name of this normalization transformation.
• Key "EPSG" : EPSG code of the data coordinates in the file.
• Key "EPSG_Window" : EPSG code of the plot projection.
• Key "Left_Lower_Window_Coordinates" : world coordinates (according to EPSG) the lower left corner of the projection window.
• Key "Right_Upper_Window_Coordinates" : world coordinates (according to EPSG) the upper right corner of the projection window.
• Key "Left_Lower_NDC_Coordinates" : picture coordinates (NDC within [0.0,1.0]) the lower left corner of the projection window.
• Key "Right_Upper_NDC_Coordinates" : picture coordinates (NDC within [0.0,1.0]) the upper right corner of the projection window.
• (optional) Key "Autoscale" : automatic adjustment (.true.) of scales in X- and Y-direction. Default is .false. (no adjustment).
• (optional) Key "Scale_Bar_Request" : Request drawing a scale bar. Autoscale needs to be on.
• (optional) Key "NTN_Framing" : Type of the coordinate frame when displayed as map.

Hint: More info at Options of map frames.

Block "Data_Description"

The block Data_Description defines a Data_Description object. Such an object collects data descriptions and displays them together in a text field.
A block of this type is currently only needed for area charts in the horizontal plane (Layer definition with Type == XY_Data).
Control file can contain multiple blocks of this type.

• Key "Data_Desc_Name" : unique name of the text field for data descriptions.
• Key "Data_Desc_Plot_Area" : image area for the Data_Description text box.
• (optional) Key "Data_Desc_Draw_Frame" : draw a frame around the Data Description text box TRUE/FALSE.
• (optional) Key "Data_Desc_Color_Name" : name of the color for text and frame.

Block "LineChart"

The block LineChart is used to define a line diagram.
A "LineChart" has only one X- and one Y-axis. A secondary Y-axis must be realized by defining a second "LineChart" object on the same drawing area and with the same X-axis.
Any number of LineCharts can be stacked. The associated axes can be positioned on all four sides of the diagram and can also be moved away from the drawing area by different distances. Thus, for example, on the sheet "one" time series diagram with three Y-axes can be generated that represents the curves for flow amount, flow direction and salinity together.
Control file can contain multiple blocks of this type.

• Key "LineChart_Name" : unique name of the line chart and the possibility of assigning a different plot level to the diagram.
• Key "LineChart_Type" : type of line chart.

• TG = Time series; Data over time
• PG = Profile chart; Data over profile axis
• GZ = Depth profile; 3D data along depth axis

• Key "LineChart_Area" : image area spanned by the diagram axes.
• Key "LineChart_Extent" : total area occupied by the diagram on the image.
• Key "LineChart_X-Axis" : X-axis of the diagram and its positioning.
• Key "LineChart_Y-Axis" : Y-axis of the diagram and its positioning.
• (optional) Key "LineChart_Legend_Box" : name of a Legend_Box, the object/area in which the curve legends of the diagram are stored and presented.
• (optional) Key "LineChart_Route_Dataset" : name of a dataset with profile route for sorting and filtering data to be displayed.
• (optional) Key "LineChart_PLR_Representation" : line Symbolization for the data curves of this diagram.
• (optional) Key "LineChart_PMR_Representation" : marker Symbolization for the data curves of this diagram.
• (optional) Key "LineChart_PLR_Palette" : color palette and start color for line symbols of this line chart.
• (optional) Key "LineChart_PMR_Palette" : color palette and start color for marker symbols of this line chart.
• (optional) Key "LineChart_FillArea_Between_Series" : Coloring of areas between two data series.
• (optional) Key "LineChart_FillArea_Series_Values" : Coloring of areas between a data series and a specific value.

Block "Axis"

The block Axis is used to define a diagram axis.
An axis definition can be used for varius diagrams. For example superposed "LineCharts" or several diagrams arranged one below the other with the same time axis.
Control file can contain multiple blocks of this type.

• Key "Axis_Name" : unique name of the axis definition.
• Key "Axis_Type" : type of axis.

• T = time axis
• G = axis for physical quantities
• P = profile axis
• Z = depth axis

• (optional) Key "Axis_Value_Range" : value range of the axis.
• (optional) Key "Axis_Date_Range" : time range of the axis.
• (optional) Key "Axis_Scale_Logarithmic" : switch logarithmic scaling LOG10 on TRUE/FALSE.
• (optional) Key "Axis_Invert_Profile_Route" : switch invert the route of a profile axis TRUE/FALSE.
• (optional) Key "Axis_Scale_Multiplicator" : multiplication factor for axis scaling.
• (optional) Key "Axis_Display_Name" : axis title, will be used instead of the original name given in the input data.
• (optional) Key "Axis_Display_Unit" : physical unit in which the data should be converted for the graphical presentation.

Hints:
The original unit of the data and the target unit must be known in the configuration file phydef.cfg.si.dat. In addition, the SI-base (dimension) of the units must be identical.

• (optional) Key "Axis_Labels_EquiDist_Value" : equidistant values for labeling along the axis.
• (optional) Key "Axis_Labels_EquiDist_Date" : equidistant dates for labeling along the axis.
• (optional) Key "Axis_Labels_at_Values" : list of values for labeling along the axis.
• (optional) Key "Axis_Labels_at_Dates" : list of dates for labeling along the axis.
• (optional) Key "Axis_Line_Representation" : name of a Poly_Line_Representation for the representation of the axis line.
• (optional) Key "Axis_Text_Representation" : name of a Text_Representation for the axis labeling (only influencing the font color).
• (optional) Key "Gitternetz_Representation" : name of a Poly_Line_Representation for the gridlines or switch off these lines with NONE.
• (optional) Key "Tickmark_Representation" : formatting or switching off axis tickmarks.

• Parameter 1 = name of a color for the tickmarks
• Parameter 2 = width of the tickmark line
• Parameter 3 = length of tickmarks in image coordinates; 0.0 turn it off!

• (optional) Key "Axis_Additional_Line_Value" : draw an additional line vertical to the axis at a certain value.
• (optional) Key "Axis_Additional_Line_Date" : draw an additional line vertical to the time axis at a certain date.
• (optional) Key "Axis_Additional_Line_Coord" : draw an additional line vertical to the profile axis at a certain location.
• (optional) Key "Characters_along_Axis" : allows the manipulation of the font size of the axis labeling.
• (optional) Key "Axis_Number_Format" : Format specification for numerical values of the axis scaling.

Block "DataRow"

The block DataRow is used to describe a data series, or a group of data series.
Due to the data addressing in the DataSet, a DataRow description can result in several data series. All these data series end up in the same line diagramm.
Blocks of this type are needed for line charts.
Control file can contain multiple blocks of this type.

• Key "DataRow_Name" : unique name of the data row description.
• Key "DataRow_Dataset" : name of the dataset to be displayed. Or a valid connexion (OPERATOR string) made out of known data sets, e. g. [DSet2-DSet1]/[DSet1+DSet2], ABS[DSet], SQR[DSet] or G18[DSet].
• Key "DataRow_LineChart" : name of the LineChart, i.e. of the line diagram in which the data series are to be drawn.
• (optional) Key "DataRow_PLR_Representation" : line symbolization for the data curves of this data series.
• (optional) Key "DataRow_PMR_Representation" : marker symbolization for the data curves of this data series.
• (optional) Key "DataRow_PLR_Palette" : color palette and start color for line symbols of this data series.
• (optional) Key "DataRow_PMR_Palette" : color palette and start color for marker symbols of this data series.
• (optional) Key "DataRow_NoValue_Handling" : Handling invalid values in the data series.

• Luecke = Points without data are not displayed
• Interpolation = a straight line closes the data gap in the curve

• (optional) Key "DataRow_NOBS_Filter" : filter for displayed data based on ancillary variable with type number of observations:
  • parameter 1: filter type:
    • EQ = display data only for a fixed number of observations;
    • LE = display data for a certain number of observations or less;
    • LE = display data for a certain number of observations or more.
  • parameter 2: filter value:
    • 0 = maximum number of observations;
    • N = specified number of observations;
    • -M = maximum number of observations minus M.

Block "Legend_Box"

A legend box collects names and symbolizations of data curves and displays them together in a text field. A legend field can accommodate curve descriptions from different diagrams.
A block of this type is only needed by line charts.
Control file can contain multiple blocks of this type.

• Key "Legend_Box_Name" : unique name of the legend field.
• Key "Legend_Box_Plot_Area" : image area for the legend field.
• (optional) Key "Legend_Box_Draw_Frame" : draw a frame around the legend field TRUE/FALSE.
• (optional) Key "Legend_Box_Color_Name" : name of the color for text and frame.

Block "Textbox"

Description of one free text field.
An empty text box can act as rectangular frame, with the color, type and width of the line being adjustable. If you give the text box a background color, you can use it to cover a particular area of the diagram.
Control file can contain multiple blocks of this type.

• Key "Name" : unique name of the text box.
• Key "Plot_Area" : image area for the text box.
• (optional) Key "Text_Line" : one line of the text box. Specification of several lines possible.
  Placeholder for system information:

• <SYS_DATE> will be replaced by current date.
• <SYS_TIME> will be replaced by current time.
• <SYS_USER> will be replaced by User ID.

Placeholder for text box, which is connected to a Layer:

• <LAY_DSET> will be replaced by the name of the dataset associated with the layer.
• <LAY_DIM1> will be replaced by the info text for the 1st dimension of the displayed data set.
• <LAY_DIM2> will be replaced by the info text for the 2nd dimension of the displayed data set.
• <LAY_DIM?> etc. to the number of data set dimensions.

Hint: Linking is realized in the layer block via KEY Layer_Description_Textbox.

• (optional) Key "Color_Name" : colors of the textbox.
  • parameter 1: for text and frame
  • (optional) parameter 2: for background
• (optional) Key "Draw_Frame" : draw a frame around the text box TRUE/FALSE.
• (optional) Key "Frame_Style" : appearance of the text box frame.
  • parameter 1: line width
  • (optional) parameter 2: line type
• (optional) Key "Fixed_Width" : character-wise writing with constant width or not.
• (optional) Key "Horizontal_Char_Space" : Horizontal character distance factor for character-wise writing.
• (optional) Key "Vertical_Line_Space" : Vertical line spacing factor.
• (optional) Key "Font_Size" : Font size can be specified possibly.
• (optional) Key "Font_Size_Factor" : Factor for manipulating the calculated font size.

Block "Poly_Marker_Representation"

Description of one type of marker symbols.
Control file can contain multiple blocks of this type.

Block "Fill_Area_Representation"

Description of one type of fill area symbolization.
Control file can contain multiple blocks of this type.

Block "Poly_Line_Representation"

Description of one type of line symbolization.
Control file can contain multiple blocks of this type.

Block "Text_Representation"

Description of one type of text symbolization.
Control file can contain multiple blocks of this type.

Block "Vector_Representation"

Description of one type of vector symbolization.
Control file can contain multiple blocks of this type.
Hint: More info at NCPLOT: Types of vector symbols.

General Remarks

1. While reading this steering data file the dictionary file ncplot_dico.dat will be automatically accessed in directory $PROGHOME/dic/ to support input.
2. If no such file exists in the working directory, NCPLOT accesses the following configuration files from the directory $PROGHOME/cfg/:
   • colors.cfg.dat: File with definitions of colors.
   • palettes.cfg.dat: File with references to files with color palette definitions.
   • bounds.cfg.dat: File with interval definitions for legends.
     Hint: The bounds file should be better stored within a project in the working directory.
3. The following standard configuration files from the directory $PROGHOME/cfg/ are required:
   • gkssystem.rechnername.dat: GKS parameter file.
   • phydef.cfg.si.dat: Configuration file for units and their relation to the SI system.

Programs using this Type of File

NCPLOT

Example-File

$PROGHOME/examples/ncplot/ncplot.dat

---

back to: File Descriptions

---

Overview