NAME

strutplot - plot self-contacts of tube with Geomview VECT core as PostScript

SYNOPSIS

strutplot -e <eps> -t <ticks> -kgsc <input file> -o <output file> --strutfile <strut file>

DESCRIPTION

strutplot is a flexible tool for visualizing the self-contacts of a tube in 3-space as a two-dimensional plot. Each contact is represented by a pair of arclength values along the input curve (s,t) with s > t, and a box is placed at the corresponding position on a triangular plot. For links, the components are taken in the order they are presented in the VECT file, and arclength is cumulative from component to component. So if the first and second components of a link have total arclength 2 and 4, respectively, then points on the first component are plotted with arclength values in [0,2) and points on the second component are plotted with arclength values in [0,4).

To find ``contacts'', the program does the following. If the function d(x,y) gives the space distance between two points x and y on a polygonal curve in 3-space, then strutplot plots all local minima of d(x,y) (excluding distances in the form d(x,x)=0) whose distance values are within eps of the closest such pair. Half of this distance represents the radius of the largest embedded tube around the core curve and is called the thickness of the core curve. The local minimum pairs plotted are known as struts.

The default visualization style for the plot includes automatic identification and highlighting of regions of the curve with no contacts, which should be ``straight segments'' in a tight polygonal knot, and regions with radius of curvature equal to the tube radius, which are called ``kinks'', as well as a plot of the discrete curvature (MinRad) of the polygonal core curve, and a (hopefully) helpful key to the plot. These additional features, and many others, can be turned off with the command-line options given below.

strutplot accepts up to 10,000 input files at a time. By default, it will process them individual, leaving plots in the current directory, but the --combine option will cause it to generate a multi-page PS document combining the plots for all input files.

OPTIONS

--help: Displays a help message showing the options for strutplot.
-e eps, --epsilon=eps: strutplot will display all pairs of points on the curve which are local minima for the self-distance function whose distance is within eps of the closest such pair. eps defaults to 0.01.
-l levels, --levels=levels: strutplot efficiently identifies pairs of points of interest using an octree-based clustering algorithm called octrope. The number of levels in the octree affects the resolution at which edges are clustered-- a higher number of levels allows more pairs of edges to be eliminated from struts' search before the code begins checking pairs of edges against one another. But this speedup must be balanced against the overhead incurred in building a larger tree.; The user can fine-tune this tradeoff by setting levels. Setting levels = 1 reduces the algorithm to checking all pairs of edges (very slow), while for an n edge link the default is levels = 0.75*log2(n).
-v verblevel, --verbosity verblevel: The user can print debugging information by setting verblevel from 0 (lowest) to 9 (highest). Usually useful only for library maintainers.
file: The input file, expected to be in Geomview VECT format. If the filename is infile.vect, the output file is named infile.stplot.ps or infile.stplot.eps, unless this behavior is overridden by the -o command-line option or multiple input files are given, in which case the output appears in combined_plots.ps. This argument is not optional.
-k, --nokinks: Disables automatic highlighting of ``kinks'' where the radius of curvature is equal to the thickness.
-g, --nogrid: Disables plotting of a background grid.
-s, --nostraight: Disables automatic highlighting of ``straight segments'' where there are no struts touching a certain region of the curve.
-c, --nokappa: Turns off the subplot of the plot of the curvature of the core curve at the bottom of the plot.
--strutsize x: The size of the box used to indicate a strut, as a multiple of the average edgelength of the input polygon.
--make-eps: Attempts to generate output in EPS format. This option is currently not entirely stable, and we recommend that users generate PostScript (PS) output and then add convert to EPS with epstool.
--combine: Combines the plots from all input files into one multipage PS document. The resulting file should be fully Adobe DSC compliant, but has problems with certain previewers for reasons we don't yet fully understand. (Comments welcome from PostScript gurus!) We have had good luck with the gv PostScript viewer, however.
--nokey: Disables display of the key for each plot.
--strutfile filename: The the liboctrope manpage library function octrope_strutfile_write can write a list of struts to disk from a user application, to be read by the corresponding procedure octrope_strutfile_read. If the --strutfile option is given with a valid file in this format, strutplot will load and display this list of struts, instead of calculating its own. This is the only way for ridgerunner users to display ``compression'' data for struts.
-t n, --ticks <n>: By default, strutplot places 10 equally-spaced tick marks on the sides of the plot. This number can be adjusted with the -t option.
--nocompressions: If a strut file was loaded with --strutfile, the struts can be colored by ``compression''. This option turns off compression coloring. The color scheme for compressions is likely to change in future versions of strutplot.
-w x, --width x: This option sets the width of the plot (in inches). The default is 5.0. This is mostly a matter of user convenience, since the PostScript output from the program can be arbitrarily scaled anyway.
-sl, -sh, -tl, -th, --s_clip_low, --s_clip_high, --t_clip_low, --t_clip_high: These options, each of which should come with an argument in [0,1], clip the displayed struts to a rectangle in the st plane. The argument is a fraction of the total arclength of the displayed curve.
--nobackground: Disables display of the colored background for the plot.
--nodsc: Outputs ``raw'' PostScript instead of following the Adobe Document Structuring conventions. This can cause some PostScript previewers to crash, and others to suddenly function, so toggling this option may help if you have difficulty working with the output from strutplot.
-o file, --outfile file: This option sets the output filename, overriding any default behavior for the program.

EXAMPLES

Plot (in PostScript) all nontrivial local minima of the self-distance function with length within 0.01 (the default) of minimum length for the file 3_1.vect:

 strutplot 3_1.vect

Plot nontrivial local minima with length within 0.0001 of minimum:

 strutplot -e 0.0001 3_1.vect

Plot only struts whose arclength coordinates are in the middle third of the curve

 strutplot -sl 0.33 -sh 0.66 -tl 0.33 -th 0.66 3.1.vect

Write the plot to the file myplot.ps:

 strutplot 3.1.vect -o myplot.vect

AUTHORS

Ted Ashton and Jason Cantarella

LICENSE RESTRICTIONS

This program is covered by the GNU General Public License for free software, modified as follows: Any publication of plots made by strutplot must acknowledge the software and include a citation of the paper A Fast Octree-Based Algorithm for Computing Ropelength (arXiv:math.DG/0409416).