CGI Parameters
- for CGI the parameters are encoded as param=value
- for command-line, they look like -param value
Data source and destination
| param | default value | value description |
|---|---|---|
| btc_id | mandatory |
One of the following:
|
| ifmt | optional |
input file format: asnt (ASN text), asnb (ASN binary). Note: the input file format is auto-detected. This parameter is optional. |
| output_file | command-line app only | redirects output to a given file |
| imgfmt | png | one of: png, jpg, pdf. PDF mode is not compatible with setting viewports |
| returntree | false | whether or not put the source BioTreeContainer into JSON result |
| returntreedict | false | if true, put the dictionary portion of the BioTreeContainer into the JSON result |
| dltree | false | Return BioTreeContainer as a netcache object exported in the format ofmt. The netcache ID for this object is returned as treekey in TV_TreeImgDesc. |
| nodereturnmode | full | Set to 'full', 'brief' or 'local'. 'brief' mode will only return information for selected nodes and, if returnselchildren is true, their children in TV_TreeImgDesc. 'local' will only return information on the nodes of tiles being rendered in the current cgi call. |
| returnselchildren | false | If nodereturnmode is 'brief', this will force the return of the children of selected nodes |
| maxselectreturn | -1 | If > -1, then this limits the number of selected nodes that will be returned to the specified value |
| nodereturndistthreshold | 6.0 | If the distance between nodes is less than this value, node and label position data will not be returned |
| featnames | blank | when treturning node data, "seq-id", "seq-title" and "accesion-nbr" are always returned unless featnames "!none". Any additional features can be requested in the comma separated list featnames. If featnames is "*", all features will be returned. |
| ofmt | optional | Output file format: asnt (ASN text), asnb (ASN binary), xml (XML format), newick (Newick tree format), nexus (NEXUS format). |
| attriburl | optional | URL which should return phylogentic-tree compatible attributes file. Returned file is used to update node features. |
| attribupdate | optional | If true, the updated tree is saved. This only works if the tree was read from netstorage. |
| descfmt | json | format of returned tree description - one of: json, asnt, asnb, xml |
| rendertonetcache | true | if set to false, will output the image directly to CGI/command-line app output; otherwise will save it to NetCache and return tree image information in JSON format |
Image Dimensions
| param | default value | value description |
|---|---|---|
| width | mandatory if dynamicviewport is not true | width of the area to draw the tree. If dynamicviewport is true, providing width enables vertical-only zoom. |
| height | mandatory if dynamicviewport is not true | height of the area to draw the tree. Ignored if dynamicviewport is true. |
| tilewidth | optional; -1 | Width of a single tile when rendering multiple tiles. Should be a divisor of width. Ignored on calls with dynamicviewport=true |
| tileheight | optional; -1 | Height of a single tile when rendering multiple tiles. Should be a divisor of height. Ignored on calls with dynamicviewport=true |
| maxdim | optional; 8192 | Maximum tile dimension - for browsers that won't support larger images |
| rendertiles | optional; blank | List of tiles to render in the format (x1,y1), (x2,y2),...(xn,yn) where x and y are the 0-based indices of the tile in the set of all tiles. If rendertiles is blank, all tiles will be rendered |
| dynamicviewport | optional; false | if true, the viewport may be automatically adjusted to match the tree size; the new size will be returned in JSON (see Overall image information) |
| autoaspectratio |
optional; false requires dynamicviewport, clientviewportwidth and clientviewportheight |
compute optimal window size - one that is large enough for the labels to appear and which is proportional, as much as possible, to clientviewportwidth and clientviewportheight. The size of the optimal image is returned in renderingparameters as minzoomwidth and minzoomheight. If pctmaxzoom is not specified, the returned image is this same size. |
| pctmaxzoom | optional; -1 | This is a number between 0 and 100 that can be optionally provided along with autoaspectratio. When provided, both minimum and maximum image dimensions will be returned with renderingparameters as (minzoomwidth, minzoomheight) and (maxzoomwidth, maxzoomheight). The size of the returned image will be interpolated between these two sizes based on pctmaxzoom. |
| maxzoomscaler | optional; 1.5 | Scales the maximum zoom - a value of 1.5 for example indicates that the user will be allowed to zoom in until 1.5 times the zoom level at which labels appear |
| generateoverview |
optional; none options are: none, with-image, or without-image |
Tell server to create a separate overview image with size equal to the client viewport size. If without-image is specified the normal full size image will not be generated. Overview image is returned via netcache ID. |
| clientviewportwidth | optional; 0 | width of the client viewport. Also used with autoaspectratio |
| clientviewportheight | optional; 0 | height of the client viewport. Also used with autoaspectratio |
| clientviewportx | optional; -1 | The x coordinate of the viewport relative the the overall (possibly tiled) image. Allows server to calculate which tiles overlap the client viewport in its current position |
| clientviewporty | -optional; 1 | The y coordinate of the viewport relative to the overall (possibly tiled) image. Allows server to calculate which tiles overlap the client viewport in its current position. |
| renderclientoverlap |
optional; no-overlap options are: no-overlap, client, selection, or node-id |
If we are rendering tiles, indicates if we only want to render tiles that overlap the client viewport coordinates, the current selection or first node in querynodeIDs. |
| margins | optional; 0 px | Same margins on all sides |
| bottommargin | optional; same as margins | If set, overrides the bottom margin (even if margins is set) |
Tree layout and appearance
| param | default value | value description |
|---|---|---|
| renderer | optional; rect | shape of the rendered tree, one of: rect, slanted, radial, force, circular |
| distmode | optional; true | flag whether to take distance into account when rendering the image (see also dist feature in Features with special meaning) |
| renderscale | optional; true | if true, scale marker will be rendered on the image |
| solidleaves | optional; false | if true, all leaf nodes will be drawn in a uniform solid color, otherwise leaves will have highlights like other nodes. |
| edgehighlight |
optional; none. options are: none, image, overview, both |
if image or both, longer edges of main image are highlighted (darker) than other edges and if overview or both longer edges in overimage are highlighted |
| labelvis | optional; leaf | controls which kinds of nodes have their labels printed on the image, one of: leaf, all, none |
| labelformat | optional; $(label) | format string for generating a node label from node features (see Features with special meaning) |
| maxlabellen | optional; -1 (no maximum) | Truncate all labels with length greater than maxlabellen |
| labelspacing | optional; 2.0 | scale dynamic viewport to adjust label spacing, 1.0=>minimum, 2.0=>doublespaced |
| rotatedlabels | optional; false | if true and renderer=circular, render labels at an angle if needed to avoid overlap |
| horizspacing | optional; 7.0 | scale horizontal spacing between branches as a factor of node size |
| fontface | optional; default: “Helvetica” | one of strings understood by CGlTextureFont::FaceFromString(), see fontface values |
| fontsize | optional; 10 | in points |
| forcesquare | optional; false | Set to true or false. If true, tree will be rendered to a square viewport. Useful only for circular layout mode to force a true circle rather than an ellipse. |
| nodesize | optional; 3px | radius of a single (default-sized) node |
| linewidth | optional;1px | width of the tree branch lines |
Tree node selection and ordering
| param | default value | value description |
|---|---|---|
| collapsednodeIDs | optional; empty | if set, collapse the listed node IDs (and all nodes under them, so only the nodes closest to the root need to be listed) |
| collapsetoviewport | optional; false | if true, collapses nodes (most distant first) so that tree will fit in(clientviewportwidth/height) at a resolution that allows labels to be drawn (any nodes collapsed in data source will first be expanded). nodes with property $PRIORITY>=1000 will not be collapsed |
| expandall | optional; false | if true any nodes collapsed in the asn will be expanded |
| setmidpointroot | optional; false | if true, tree is re-rooted using the midpoint algorthm |
| sort |
optional; false options are: children, distance, labels, subtreelabels |
if specified, sort children of each node in specified order |
| sortorder |
optional; desc options are: asc, desc |
When sort is specified, specifies whether nodes should be sorted in ascending or descending order |
| rootnodeID | optional; -1 | if not -1, re-root the tree at the specified node ID |
| selectednodeIDs | optional; empty | comma-separated list of node ids to be shown as selected |
| deselectednodeIDs | optional; empty | comma-separated list of node ids from the tree to be de-selected. nodes from selectednodeIDs are selected before nodes from deselectednodeIDs are deselected. |
| subtreenodeID | optional; -1 | if not -1, only a subtree starting from the node with this ID will be shown |
| neighborhoodnodeIDs | optional; empty | Show nodes with the specified IDs as selected along with any other nodes that can be reached by recursively traversing connected branches up to a distance of neighborhooddist. The center and size of the selected nodes are also returned in the JSON struct neighborhood of TV_TreeImgDesc |
| neighborhooddist |
optional; 0.0. required if neighborhoodnodeID is provided |
The maximum distance from neighborhoodnodeID, traversed recursively, for nodes to be included in the neighborhood selection set. |
| querynodeIDs | optional; empty | list of node IDs for which we will return JSON data (even if nodes are collapsed) |
| query | optional; empty | a valid query of the same format used in Genome Workbench. Nodes matching the query criteria will be rendered as selected and returned to the caller |
| zoomtoquery | optional; false | if true zoom in or out so that all of the selected nodes will fit in the client viewport (clientviportwidth/height) |
Test parameters
| param | default value | value description |
|---|---|---|
| test_delay | 0 | delay in whole seconds before input starts to be processed, any value <0 or >60 will cause a delay of 60 seconds |
nc_fetch.cgi parameters
| param | default value | value description |
|---|---|---|
| key | mandatory | Netcache id of the generated image (obtained from img_key in the JSON return) |
fontface values
List of values allowable for fontface parameter can be found in http://www.ncbi.nlm.nih.gov/IEB/ToolBox/CPP_DOC/lxr/source/src/gui/opengl/gltexturefont.cpp (look for CGlTextureFont::s_FontNames). From a C++ application, they can be obtained by calling CGlTextureFont::GetAllFaces().
Table of Contents
- Tree Viewer documentation home
- Tree Viewer application home
- For Users
- User Tutorials
- For Developers
- Related Resources