ConvertBot: creates a new plot feature and adds it to a plotter

2020-04-27T22:04:40Z

creates a new plot feature and adds it to a plotter

New page

creates a new plot feature and adds it to a plotter
<pre>
<NAME> The Feature class name or fully qualified class name (rarely used).
<LABEL> Results label to referencing the object.
<TABLE> Table of arguments to initialize the object via the setKey interface.
<PLOT> The ID of plotter to which to add feature.

This command creates a new Feature object for attaching to a plotter. All the
positions are in real world coordinates (RWC) in terms of the plotter. If they
are out of the plotter's bounds, they will not be displayed.

The class name specified by <NAME> specifies a custom Feature subclass.
Most users will simply leave <NAME> blank and use the default (which is
documented here). If <NAME> is not a fully qualified class name, a prefix of
nxm.sys.libg.Feature is assumed.

If <TABLE> is specified, layer.setKey() will be called for each element in the
table. The following values in the <TABLE> are typically set:

NOTE: Quotes are recommended around table value to prevent collisions with
results parameters!!!

NAME="<name>" Sets the name/label of the feature (used by plotter).
TYPE="<type>" Sets the feature type (mask value) (see below).
COLOR="<color>" Sets the color of the feature.
FILLCOLOR="<color>" Sets the fill color for certain feature types (defaults
to COLOR= if this is not set.
X=<x>,Y=<y> Sets the center point of the feature.
DX=<dx>,DY=<dy> Sets the width and height of the feature (where
applicable). Including diameter of CIRCLE features
XMINMAX=<x1,x2> Sets the X and DX values (calculated from given input)
YMINMAX=<y1,y2> Sets the Y and DY values (calculated from given input)
T=<t>,DT=<dt> Sets the parameters for time-based features (see below).
SEMIMAJOR=<semimajor> Sets the semi-major for the ELLIPSE features (in meters)
SEMIMINOR=<semiminor> Sets the semi-minor for the ELLIPSE features (in meters)

If <LABEL> is specified, a reference to the feature is stored in the results
table.

If <TABLE> NAME is not specified, the feature is given a unique name. The name will be <LABEL>, if
that is available and unique.

If <PLOT> is specified, the feature is added to the named plotter.

Types:
The feature type is set using: table={TYPE=<type>}
Where <type> is one of the following feature types or a combination of the
following feature types (e.g. table={TYPE=HLINE|VLINE}).

All positions are in real world coordinates (RWC). Most sizes are in RWC
except for when SYMBOL type is used when drawing features of a fixed
pixel size (i.e. their size is constant at all zoom levels). When drawing a
feature whose size matches real world coordinates use the all other types such
as BOX, CIRCLE, OVAL, etc.

SYMBOL
If the feature is a SYMBOL (TYPE=SYMBOL in <table>) then the parameters of
that symbol can be set by putting a LINE={..} entry in the table. The most
commonly used symbol settings are:
SYMBOL=<sym>
Where <sym> is one of the following:
CROSS - A 'x' symbol. TRIANGLE, TRI - A triangle symbol.
PLUS - A '+' symbol. UTRIANGLE, UTRI - A triangle (up).
STAR - A '*' symbol. DTRIANGLE, DTRI - A triangle (down).
CIRCLE - A circle symbol. RTRIANGLE, RTRI - A triangle (right).
SQUARE - A square symbol. LTRIANGLE, LTRI - A triangle (left).
DIAMOND - A diamond Symbol. ASCII-<str> - An ASCII string <str>.
DOT - A small dot/pixel. <single letter> - A single ASCII letter.
ARROW - A block arrow. NONE - No symbol used.
AERO - An airplane symbol.

Note: As of NeXtMidas 2.7.0, an image can be used in place of the pre-
defined Symbols above by replacing the symbol name with the file
name for the image, (e.g. SYMBOL="nxm.sys.dat.network.png" )

SYMBOLSIZE=<size>
Sets the symbol size (in pixels).

SYMBOLFILL=[YES|NO]
Indicates if the symbol should be filled in ('yes' or 'no').

SYMBOLANGLE=<radians>
SYMBOLANGLEDEG=<degrees>
SYMBOLHEADING=<degrees>
Use ONE of these to set the symbol angle.
SYMBOLANGLE - The angle of the symbol (counter-clockwise from east)
SYMBOLANGLEDEG - The angle of the symbol (counter-clockwise from east)
SYMBOLHEADING - The angle of the symbol (clockwise from north):
North: 0 or 360 East: 90
South: 180 West: 270

DATA
Highlights the enclosed data. Typically used on a line plot to highlight a
portion of interest.

HBAR (Since NeXtMidas 3.3.2)
Draws horizontal bar (filled box using FILLCOLOR) at Y-DY/2 and Y+DY/2
along the *vertical* axis.
E.g. this fills in the area between the HLINE type.

VBAR (Since NeXtMidas 3.3.2)
Draws vertical bar (filled box using FILLCOLOR) at X-DX/2 and X+DX/2.
along the *horizontal* axis.
E.g. this fills in the area between the VLINE type.

HLINE
Draws two horizontal lines (one at Y-DY/2 and one at Y+DY/2 along the
*vertical* axis).

VLINE
Draws two vertical lines (one at X-DX/2 and one at X+DX/2 along the
*horizontal* axis).

XLINE (Since NeXtMidas 2.9.0)
Draws two lines with respect to the Plot's view (one at plot x=X-DX/2
and one at plot x=X+DX/2). In the normal Y vs X plot these lines will be
vertical, and in the rotated X vs Y plot these lines will be horizontal.
(Note: If DX is zero, only one line will be drawn.)

YLINE (Since NeXtMidas 2.9.0)
Draws two lines with respect to the Plot's view (one at plot y=Y-DY/2
and one at plot y=Y+DY/2). In the normal Y vs X plot these lines will be
horizontal, and in the rotated X vs Y plot these lines will be vertical.
(Note: If DY is zero, only one line will be drawn.)

BOX
Draws a box centered at (X,Y) with height DY and width DX. To fill the box
use TYPE="BOX|FILLED".

CIRCLE
Draws a circle centered at (X,Y) with diameter of MAX(DY_in_pixels,
DX_in_pixels), where the number of pixels for width or height is dependent
on the scale for that axis. To fill the circle use TYPE="CIRCLE|FILLED".

OVAL
Draws an oval centered at (X,Y) with height DY and width DX. To fill the
oval use TYPE="OVAL|FILLED".

ELPS
Draws a geodetic ellipse centered at (X,Y) ellipse dimension SEMIMINOR,
SEMIMAJOR, and TILT. SEMIMAJOR & SEMIMINOR are in meters. TILT is in
cardinal degrees (90 = horizontal). The ellipse will follow the curvature
of the Earth. ELPS is designed for Map views ONLY.

LTAG,RTAG,TTAG,BTAG
Labels the feature with a tag along the left/right/top/bottom axis. The tags
are drawn outside of the axis unless IPLT is specified.

DTAG
(NOT USED)

PEAK
(NOT USED)

IPLT
Shows the tags (see LTAG,RTAG,TTAG,BTAG) inside the plot axis.

VRIDE
The vertical position of the feature (Y) should ride along the plot value.
Typically used in combination with SYMBOL on a line plot to mark the data
value at a given X value.

OSYMBOL
Legacy feature, in most cases it is best to use TYPE="SYMBOL",
LINE={SYMBOL="CIRCLE"} in place of this.

LABEL
Same as TEXT. Deprecated since NeXtMidas 2.3.0.

INVERSE
When coloring the feature use the inverse color of the plot data. Typically
used over a raster plot to ensure that the feature will stand out regardless
of the color of the plot.

TEXT
Show a text label for the feature.

TRI
Legacy feature, in most cases it is best to use TYPE="SYMBOL",
LINE={SYMBOL="TRI",SYMBOLFILL="ON"} in place of this.

FILLED
Fills a BOX, CIRCLE, or OVAL feature with FILLCOLOR. Note that this has no
affect on symbols, which have a separate SYMBOLFILL option (see above).

Time-Based Features:
Note: Time-based features are disabled by default by setting dt=-1, they can
be enabled by setting dt>=0.

Time-based features comprise a special class of features. These features are
typically used on falling rasters of real-time plots to indicate a time-
relevant event. To use a feature as a time-based feature simply set dt to a
non-negative value. This will cause the values of y and dy used when plotting
the feature to be computed on t and dt rather than using a fixed y and dy.
Time-based features "expire" as soon as ANY part of the feature is in the
"past" (i.e. outside of the current range of the plot). Once a feature has
"expired" it will be drawn over or erased.

For performance reasons, time-based features with dt > 0 that "wrap around"
the plot will not be drawn in "wrapped" form. Please use the line features
in place of box features where this may occur.

Time-based features use the first plot layer (i.e. the first pipe/file) as
their time reference. If there are no layers in the plot the features may not
be drawn in the correct position.

Changing values in Features:
It is possible to update an existing Feature by changing its values. For
example, to change the location of a Feature labeled 'fcirc':
nM> set fcirc.x 50
nM> set fcirc.y 10

Each of the above commands changes the corresponding Feature value and calls
refresh(). If you are updating a many attributes of feature, as of NeXtMidas
2.7.2 you can temporarily disable the call to refresh():
nM> set reg.idplot.holdRefresh features
- or -
nM> message func=sendw id=idplot name=HOLDREFRESH data=features

Warning: In order for your updates to take effect and be displayed, you must
unblock refresh().
nM> set reg.idplot.holdRefresh none
- or -
nM> message func=sendw id=idplot name=HOLDREFRESH data=none

Examples:
The following examples assume a PLOT command is issued as follows (note that
the examples should each be on one line, line breaks added to fit page):
nM> plot/bg/id=myplot apenny

1. Add a CIRCLE to the plot (that has a constant real-world size):
nM> feature label=fcirc plot=myplot &
table={NAME="CIRCLE",TYPE=CIRC,X=20,Y=20,DX=5,COLOR=YELLOW}

2. Add a CIRCLE to the plot (that has a constant screen/pixel size).
Note that X= and Y= are still in RWC:
nM> feature label=fcirc plot=myplot &
table={NAME="CIRCLE",TYPE=SYMBOL,X=20,Y=20,DX=5,COLOR=WHITE,&
LINE={SYMBOL=CIRCLE}}

3. Add a red triangle SYMBOL to the plot:
nM> feature label=fsymbol plot=myplot &
table={NAME="SYMBOL",TYPE=SYMBOL,X=20,Y=20,COLOR=RED,&
LINE={SYMBOL=TRI}}

4. Add a large red triangle SYMBOL to the plot:
nM> feature label=fsymbol plot=myplot &
table={NAME="SYMBOL",TYPE=SYMBOL,X=20,Y=20,COLOR=RED,&
LINE={SYMBOL=TRI,SYMBOLSIZE=30}}

5. Add a blue feature to the plot that has horizontal and vertical lines:
nM> feature label=flines plot=myplot &
table={NAME="FLINES",TYPE=HLINE|VLINE,X=20,Y=20,COLOR=BLUE}

6. Add an ELLIPSE to the plot tilted -45 degrees.
nM> feature label=fellipse plot=myplot &
table={NAME="ELLIPSE",TYPE=ELPS,X=20,Y=20,TILT=-45,&
SEMIMAJOR=1700000,SEMIMINOR=800000,COLOR=GREEN}

7. Remove a feature named "MYFEATURE" from the plot. The name should
correspond to the NAME= key in the table used to create the feature.
(Note this does not remove the local variable <LABEL> from the results.)
nM> invoke junk reg.idplot.removeFeature("MYFEATURE")

8. Remove a feature "MYFEATURE" from the plot. (Note this does not remove the
local variable <LABEL> from the results.)
nM> invoke junk reg.idplot.removeFeature("*")

Switches:
None

See Also: nxm.sys.libg.Feature, nxm.sys.libg.Line, nxm.sys.libg.Symbol

</pre>

[[Category:NXM_Explain]]

FEATURE - Revision history

ConvertBot: creates a new plot feature and adds it to a plotter