api
From autoplot.org
Contents |
1. Parameters
1.1. Common
- uri an Autoplot URI or a vap file.
- timeRange is the time range displayed. Note that the speparator is used to indicate if the end date is inclusive or exclusive:
2001-01-01/2001-01-02
means the end date is before 2001-01-02,2001-01-01 to 2001-01-02
means the end date is before 2001-01-02, and2001-01-01 through 2001-01-02
means the end date is before 2001-01-03. Most ISO8601 forms can be used, so for example2001-01-01T00:00/08:00
will show the first eight hours of the day, as does2001-01-01T00:00/PT8H
. In addition, to support updating or near-real-time displays, the special keyword "now" refers to the current time, soP10D/now
refers to the ten-day interval ending at the current time when the timeRange was parsed. See also Time Parsing and Formatting. - dataSetURL controls the initial URL displayed. Note "about:plugins" and "about:autoplot" are supported and useful for debugging.
- column controls the horizontal layout. Syntax is
L%+S,R%+S
, for example0%+5em,100%-10em
See help#layout. Use will allow for a stack of images created with the API with the same time axis to be aligned properly. - row controls the vertical layout. Syntax is
T%+S,B%+S
, for example0%+2em,100%-7em
See help#layout. - autolayout automatically adjust the row and column to avoid clipping labels.
- font is the font to use on the system. This must identify a font on the client's desktop, so good choices are generic, e.g., "sans-16"
- renderType explicitly specifies how the data should be rendered
- scatter draws the data as a scatter plot
- series connects the plot symbols
- stairstep (used to be histogram) draws a stepped line to indicate the sample interval
- fillToZero (used to be fill_to_zero) draws a stairstep and fills to the reference line when renderType=fillToZero.
- spectrogram renders the data as a spectrogram with bilinear interpolation. Note if the data is not suited for this, nothing will be done.
- nnSpectrogram renders the data as a spectrogram with nearest neighbor interpolation. Note if the data is not suited for this, nothing will be done.
- hugeScatter uses a faster rendering method that can handle millions of points. "series" and "scatter" becomes inefficient with more than ~40,000 points.
- color specifies the plot symbol and symbol connector color in #rrbbgg format. Specify multiple componet colors with a comma separated list.
- fillColor specifies the color in #rrbbgg format used to fill to the reference. Specify multiple componet colors with a comma separated list.
- foregroundColor is the color of the axis and labels in #rrbbgg format
- backgroundColor is the color of the drawing canvas background. (Use #rrbbgg or none for transparent)
- plot.title the title for the single panel plot.
- plot.{x,y,z}axis.label the label for the x, y, or z (colorbar) axis.
- plot.{x,y,z}axis.range the range for the x, y, or z (colorbar) axis. e.g. "2000-02-01 to 2000-02-15" or "200 to 800". With the servlet,
+
should be used in URLs instead of spaces. - plot.{x,y,z}axis.log scale type for x axis. "true" indicates use a log axis
- plot.{x,y,z}axis.drawTickLabels "true" indicates draw labels. This is the default.
1.2. Applet-only
The applet mode is not supported.
See api#Common for the list of all parameters. Applet parameters are specified as <param name="NAME" value="VALUE">
- splashImage is the image to use as the preview as the applet initializes.
- clickCallback is a javascript function to call with click info. <clickCallback>( plotid, xdatum, ydatum, xcanvas, ycanvas, clickType )
- statusCallback the name of a javascript function to call with status. It should take one string argument, which will describe the status. These include:
- readParameters the configuration parameters have been read in.
- dataSourceSet the data source is resolved.
- dataSourceLoaded the data is loaded.
- ready the initial work is complete and the applet is waiting for user interaction.
- timeCallback the name of a javascript function to call to indicate the current x-axis range. This is a string.
- clickCallback The name of a javascript function which will get the location of clicks. For most recent test version, see the latest release at Autoplot_Change_Log and select AutoplotAppletOnClick.html. See page source for usage example. Initial version: [1].
- onClick,label=Show Coordinates onClick is a javascript routine name. Show Coordinates is the label in the context menu.
- contextOverview=on (off is default.) Show two-panels, lower panel is context plot, upper panel is zoom in.
1.3. Servlet-only
See api#Common for the list of all parameters. Check the history for recent additions. The code for the servlet is here: [2]
Servlet-only parameters:
- format specifies the return format type
- image/png
- application/pdf
- image/svg+xml
- canvas.aspect. Aspect ratio for the canvas. Aspect is width/height, and simple expressions like '10/3' are handled.
- width and height (servlet only - applets should specify width and height in <applet> tag.)
- process specifies a process to apply to the loaded data.
- histogram performs a 100-bin histogram on the data. The data is autoranged to establish min, max and scale type.
- magnitude(fft) displays the frequency content of the data
- drawGrid=true turns on the grid at axis major ticks.
1.4. AutoplotServer command line
There's support for a command line server, intended to support CGI-BIN services and other applications. It has a subset of the common interface:
UNIX> wget -N http://autoplot.org/latest/autoplot.jar UNIX> java -cp ~/autoplot.jar org.autoplot.AutoplotServer --help org.autoplot.AutoplotServer 20180726 Usage: AutoplotServer -u, --uri= URI to plot, or if .vap then rescale to width and height -v, --vap= VAP to plot without scaling. -w, --width= width of result (default=700) -h, --height= height of result (default=400) -a, --canvas.aspect= aspect ratio -f, --format= output format png or pdf (default=png) -o, --outfile= output filename or - -r, --timeRange= set this to the timerange, instead of the range within the vap --enableResponseMonitor monitor the event thread for long unresponsive pauses -z, --noexit don't exit after running, for use with scripts. -q, --nomessages don't show message bubbles. --autorange autorange the Y and Z axes of each plot in the vap --autorangeFlags autorange the Y and Z axes of each plot where the autorange flag is set in the vap --rescaleFonts when the .vap is rescaled, also scale the fonts UNIX> java -cp ~/autoplot.jar org.autoplot.AutoplotServer -u 'http://autoplot.org/data/autoplot.cdf?BGSEc' -o image.png
2. Methods
2.1. Applet
Applet methods can be called from Javascript. For example, if the applet's id is applet_1, then in JavaScript, one can call
applet_1.setTimeRange( '2009-01-01' )
because the applet defines a public method setTimeRange that accepts a string parameter.
- setTimeRange(String). The string is parsed as a time range and the x axis is set to the new range.
- setDataSetURL(String). Point the applet to a new data source.
- setCanvasFont(String). Reset the canvas font. (Broken in current release.)
- setDomNode( String name, String value ). Uses Java introspection to set the value of the property identified. This uses the object serialization defined in QStream to parse strings into objects. Hopefully any type allowed in the dom tree will work here.
For example:
setDomNode( 'timeRange', '2009-05-06' ) setDomNode( 'plots[0].xaxis.log', 'true' ) # TODO: I think the indexed variables don't work presently. setDomNode( 'options.drawMinorGrid', 'true' )
- printDomNode( String name ) Uses Java introspection and QStream's serialize delegates to provide a string representation of the property. You cannot at this time get the string back because of limitations in how we use Javascript and java, but this provides a means of displaying the node in the java console. TODO: fix this limitation
printDomNode( 'timeRange' ) printDomNode( 'plots[0].xaxis.log' )
When adding to the applet's API, the thread calling the applet is considered a hostile thread and a security exception will be thrown when a setter is called. Wrap the setter in a Runnable, then pass the Runnable to SwingUtilities.invokeLater so the code is run from a trusted thread.
2.2. WebStart
The webstart server serves JNLP files which configure Autoplot to run in a number of different ways.
http://autoplot.org/autoplot.jnlp http://autoplot.org/autoplot.jnlp?URI http://autoplot.org/autoplot.jnlp?open=URI http://autoplot.org/autoplot.jnlp?version=VERSION http://autoplot.org/autoplot.jnlp?version=VERSION&URI http://autoplot.org/autoplot.jnlp?version=VERSION&open=URI
http://autoplot.org/autoplot.jnlp?uri=URI (deprecated) http://autoplot.org/autoplot.jnlp?version=VERSION&uri=URI (deprecated)
where URI
is the full URI to be placed in the address bar when Autoplot starts and VERSION
is any directory listed at http://autoplot.org/jnlp. See Main_Page#Formats_Read and below for example links. Each time a link is clicked a new instance of Autoplot is started. (Eventually there will be an option to allow the user to click a link and have the URI plotted above, below, or over an existing plot if Autoplot is already running.)
Examples
- http://autoplot.org/autoplot.jnlp?http://autoplot.org/data/autoplot.xml?BGSM
- http://autoplot.org/autoplot.jnlp?open=http://autoplot.org/data/autoplot.cdf?BGSM
- http://autoplot.org/autoplot.jnlp?version=v2013a_8&http://autoplot.org/data/autoplot.cdf?BGSM
- http://autoplot.org/autoplot.jnlp?version=v2013b_1&http://autoplot.org/data/autoplot.cdf?BGSM
- http://autoplot.org/autoplot.jnlp?version=latest&open=http://autoplot.org/data/autoplot.cdf?BGSM