api

From autoplot.org

Jump to: navigation, search

Contents

  1. Parameters
    1. Common
    2. Applet-only
    3. Servlet-only
    4. AutoplotServer command line
  2. Methods
    1. Applet
    2. WebStart

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, and 2001-01-01 through 2001-01-02 means the end date is before 2001-01-03. Most ISO8601 forms can be used, so for example 2001-01-01T00:00/08:00 will show the first eight hours of the day, as does 2001-01-01T00:00/PT8H. In addition, to support updating or near-real-time displays, the special keyword "now" refers to the current time, so P10D/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 example 0%+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 example 0%+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

Retrieved from "http://autoplot.org//api"
Personal tools