FEATURE
Jump to navigation
Jump to search
creates a new plot feature and adds it to a plotter
<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