  SLxfig Reference
  John E. Davis, with numerous contributions from Manfred
  Hanke
  Jan 10, 2015
  ____________________________________________________________

  Table of Contents


  1. Introduction
     1.1 History

  2. Function Reference
     2.1 <xfig_object>.justify
     2.2 <xfig_object>.render
     2.3 <xfig_object>.scale
     2.4 pict.rotate_pict
     2.5 xfig_add_latex_package
     2.6 xfig_center_pict_in_box
     2.7 xfig_clip_polyline2d
     2.8 xfig_compound.append
     2.9 xfig_compound.insert
     2.10 xfig_create_arrow
     2.11 xfig_ellipse.rotate
     2.12 xfig_get_color_names
     2.13 xfig_get_eye
     2.14 xfig_get_eye_roll
     2.15 xfig_get_focus
     2.16 xfig_get_latex_preamble
     2.17 xfig_justify_object
     2.18 xfig_lookup_w3c_color (name)
     2.19 xfig_make_font
     2.20 xfig_meshgrid
     2.21 xfig_multiplot
     2.22 xfig_new_color
     2.23 xfig_new_compound
     2.24 xfig_new_ellipse
     2.25 xfig_new_eps
     2.26 xfig_new_hbox_compound
     2.27 xfig_new_legend
     2.28 xfig_new_pict
     2.29 xfig_new_png
     2.30 xfig_new_polyline
     2.31 xfig_new_text
     2.32 xfig_new_vbox_compound
     2.33 xfig_pict.scale
     2.34 xfig_plot--errorbars
     2.35 xfig_plot--initialize_plot
     2.36 xfig_plot--wcs
     2.37 xfig_plot.add_object
     2.38 xfig_plot.axis
     2.39 xfig_plot.get_world
     2.40 xfig_plot.hplot
     2.41 xfig_plot.plot
     2.42 xfig_plot.plot_pict
     2.43 xfig_plot.plot_png
     2.44 xfig_plot.shade_region
     2.45 xfig_plot.title
     2.46 xfig_plot.world
     2.47 xfig_plot.world1
     2.48 xfig_plot.world2
     2.49 xfig_plot.x1axis
     2.50 xfig_plot.x2axis
     2.51 xfig_plot.x2label
     2.52 xfig_plot.xaxis
     2.53 xfig_plot.xfig_coords
     2.54 xfig_plot.xlabel
     2.55 xfig_plot.xylabel
     2.56 xfig_plot.y1axis
     2.57 xfig_plot.y2axis
     2.58 xfig_plot.y2label
     2.59 xfig_plot.yaxis
     2.60 xfig_plot.ylabel
     2.61 xfig_plot_add_symbol
     2.62 xfig_plot_add_transform
     2.63 xfig_plot_get_symbol_names
     2.64 xfig_plot_new
     2.65 xfig_plot_new_png
     2.66 xfig_plot_text
     2.67 xfig_render_object
     2.68 xfig_set_eye
     2.69 xfig_set_eye_roll
     2.70 xfig_set_focus
     2.71 xfig_set_font_style
     2.72 xfig_set_latex_preamble
     2.73 xfig_set_output_driver
     2.74 xfig_set_verbose


  ______________________________________________________________________



  1.  Introduction

  SLxfig is a S-Lang package that produces plots, drawings, etc in a
  variety of formats (.ps, .eps, .png, .jpeg,...). It accomplishes this
  via S-Lang functions that automatically run Xfig's fig2dev and LaTeX
  to produce the desired output format. See the examples page for some
  sample publication-quality plots and the code that produced them.

  1.1.  History

  In October of 2003 I was asked to give a talk at a workshop on
  modeling pileup in the Chandra CCDs and was told that it should be an
  electronic presentation using, for example, powerpoint. I installed
  the OpenOffice version of powerpoint and started working on the
  presentation. After about 30 minutes of frustration, I turned to xfig,
  which is a very flexible and simple to use drawing program familiar to
  many scientists and engineers.

  Using xfig, I proceeded to draw several grids representing the CCD
  pixels. At some point, I wanted to go back and change the orientation
  of some of the grids such as changing vertical lines to diagonal ones.
  Unfortunately, this would require recreating the grids, which would
  take time. But what if I was not happy with the new orientation and
  wanted to try another one? Clearly, a manual approach was not going to
  work. So I started to look for an automated approach to xfig. I
  searched the web and found the specification of the xfig file format
  and proceeded to write a S-Lang script to automatically generate the
  appropriate .fig file from a mathematical description of the object as
  coded in S-Lang. SLxfig was born.

  The following set of SLxfig-generated figures, which shows two
  perspectives of a pair photons interacting in the CCD, illustrates the
  solution to the orientation problem described above.

  Figure 1, Figure 2

  See the updated version of the pileup-presentation for more examples
  of SLxfig generated drawings and plots.



  2.  Function Reference

  2.1.  <xfig_object>.justify


      Synopsis
        Justify an object at a specified position

      Usage
        <xfig_object>.justify (Vector_Type X [, Vector_Type dX]);
        % or
        <xfig_object>.justify (XFig_Object o [, Vector_Type dX]);

      See Also
        ``xfig_justify_object''

  2.2.  <xfig_object>.render


      Synopsis
        Render an xfig object to a file.

      Usage
        <xfig_object>.render(String_Type filename);
        % or
        <xfig_object>.render(Struct_Type dev);

      Description
        If the argument is a filename string, the file is created
        through xfig_create_file, and the <xfig_object> is rendered.
        xfig_close_file finally closes the file and runs Xfig's fig2dev
        program on it.

      Qualifiers
        ; depth=intarray: if specified, only objects of these depths are
        rendered
        ; verbose=intval: if >=0, the fig2dev command is displayed
        ; fig=0|1: if 0 (default), the .fig file will be removed,
        otherwise kept

      See Also
        ``xfig_set_verbose''

  2.3.  <xfig_object>.scale


      Synopsis
        Scale an xfig object

      Usage
        <xfig_object>.scale (s);
        % or
        <xfig_object>.scale (sx, sy[, sz]]);

      Description
        If the .scale method is called with one argument s, the object
        is scaled by s in all directions.  If two (three) arguments sx,
        sy (and sz) are given, x, y (and z) coordinates are scaled
        differently.

  2.4.  pict.rotate_pict


      Usage
        pict.rotate_pict (theta_degrees);

      Description
        A picture object can only be rotated by multiples of 90 degrees.

  2.5.  xfig_add_latex_package


      Synopsis
        Load a package in the preamble of latex documents.

      Usage
        xfig_add_latex_package (String_Type package[, package2, ...]);

      Qualifiers
        ; prepend: package is inserted before previous packages

      Description
        Options can be added to package in square brackets:

      Example
        xfig_add_latex_package("fontenc[T1]", "mathpazo[osf]");

  2.6.  xfig_center_pict_in_box


      Synopsis
        Center a pict object in a box

      Usage
        xfig_center_pict_in_box (pict_object, X, dx, dy

      Description
        This function takes a pict object and centers it in a box whose
        width is dx and whose height is dy. The vector X denotes the
        position of the lower-left corner of the box. If the pict object
        is too big to fit in the box, then its lower-left corner will
        coincide with the lower-left corner of the box.

      See Also
        ``xfig_translate_object''

  2.7.  xfig_clip_polyline2d


      Synopsis
        Clip a list of 2d line segments

      Usage
        list = xfig_clip_polyline2d (x[], y[], xmin, xmax, ymin, ymax)

      Description
        This function clips a polyline composed individual line segments
        that run from (x_i,y_i) to (x_{i+1},y_{i+1}) at the boundaries
        of the window defined by the xmin, xmax, ymin, and ymax
        parameters. The result is returned as an xfig polyline object.

      Notes
        This function should be used if the order of the line segments
        does not matter.  Otherwise, the xfig_clip_polygon2d function
        should be used.

      See Also
        ``xfig_clip_polygon2d'', ``xfig_new_polyline_list''

  2.8.  xfig_compound.append


      Synopsis
        Append one or more xfig objects to a compound

      Usage
        xfig_compound.append(<xfig_object> o[, ...]);

      See Also
        ``xfig_compound.insert''

  2.9.  xfig_compound.insert


      Synopsis
        Insert one or more xfig objects to a compound

      Usage
        xfig_compound.insert(<xfig_object> o[, ...]);

      See Also
        ``xfig_compound.append''

  2.10.  xfig_create_arrow


      Synopsis
        Create a new arrow shape for a polyline object

      Description
        xfig_create_arrow creates a structure that can be used for
        polyline objects, e.g., with xfig_new_polyline.  All information
        are passed via qualifiers.

      Qualifiers
        ; arrow_type: shape of arrow heads (values from 0 to 14), e.g.,
        XFIG_ARROWTYPE_{STICK,TRIANGLE,INDENTED,POINTED} and others
        (default: XFIG_ARROWTYPE_INDENTED==2)
        ; arrow_style: XFIG_ARROWSTYLE_{HOLLOW,FILLED}, i.e., 0 or 1;
        indicating a filling with white or with the pen color for 0 <
        arrow_type < 13 (default: 1)
        ; arrow_thickness: (default: 1)
        ; arrow_width: (default: 4)
        ; arrow_height: (default: 8)

      Example
        % using the same (simple) shape for forward and backward arrow,
        % implicitly calling xfig_create_arrow (twice): variable a1 =
        xfig_new_polyline([0,4], [0,3] ; forward_arrow, backward_arrow,
        arrow_type=0, arrow_style=0);

        % explicitly calling xfig_create_arrow, in order to use %
        different shapes for forward and backward arrow: variable
        forw_arr = xfig_create_arrow(; arrow_type= 0, arrow_style=0),
        back_arr = xfig_create_arrow(; arrow_type=13, arrow_style=1), a2
        = xfig_new_polyline([1,5], [1,4] ; forward_arrow=forw_arr,
        backward_arrow=back_arr);

      See Also
        ``xfig_new_polyline''

  2.11.  xfig_ellipse.rotate


      Usage
        xfig_ellipse.rotate([Vector_Type axis,] Double_Type theta);

      Description
        If no axis is given, the ellipse is rotated in the x-y-plane
        around axis = vector(0,0,1).

        The rotation angle theta is measured in radians.

  2.12.  xfig_get_color_names


      Synopsis
        Get a list color names

      Usage
        Array_Type xfig_get_color_names ()

      Description
        This function returns an array of strings giving the available
        color names. This list includes the Xfig color names, user-
        defined colors, and the W3C color names.

      See Also
        ``xfig_new_color'', ``xfig_list_colors'',
        ``xfig_lookup_w3c_color''

  2.13.  xfig_get_eye


      Synopsis
        Obtain the point from which the projection of 3d space is seen

      Usage
        Vector_Type xfig_get_eye ()

      See Also
        ``xfig_set_eye''

  2.14.  xfig_get_eye_roll


      Synopsis
        Obtain the roll angle under which the projection of 3d space is
        seen

      Usage
        Double_Type xfig_get_eye_roll ()

      Description
        The roll angle is measured in degrees.

      See Also
        ``xfig_set_eye_roll'', ``xfig_set_eye''

  2.15.  xfig_get_focus


      Synopsis
        Obtain the focus point of the projection of 3d space

      Usage
        Vector_Type xfig_get_focus ()

      See Also
        ``xfig_set_focus''

  2.16.  xfig_get_latex_preamble


      Usage
        String_Typer xfig_get_latex_preamble ()

      See Also
        ``xfig_set_latex_preamble''

  2.17.  xfig_justify_object


      Synopsis
        Justify an object at a specified position

      Usage
        xfig_justify_object (XFig_Object obj, Vector_Type X [,
        Vector_Type dX]);
        % or
        xfig_justify_object (XFig_Object obj, XFig_Object o [,
        Vector_Type dX]);

      Description
        This function moves the object to the specified position X (a
        vector) and justifies it at that position according to the
        offsets specified by the vector dX. The components of dX are
        normally in the range -0.5 to 0.5 and represent offsets relative
        to the size of the object.  If the components of dX are 0, then
        the object will be centered at X.

        Alternatively, the second argument may be an XFig object o
        itself.  The position vector X is then determined from the
        position of o and the justification vector dX: obj will be
        justified relative to the outer boundary of o, unless the inside
        qualifier is set, in which case it will be justified relative to
        the inner boundary.

      Qualifiers
        ; inside: justify obj relative to the inner boundary of o

      Example
        For dX = vector (0,0,0): the object obj will be justified
        concentrically with o.

        For dX = vector (0,-0.5,0) (i.e., obj will be horizontally
        centered and vertically aligned at its lower baseline): X is the
        horizontal center of the upper vertical baseline of o such that
        obj will be placed on top of o.

        For dX = vector (0,-0.5,0), together with the inside qualifier:
        X is the horizontal center of the lower vertical baseline of o
        such that obj will be coaligned with o at their lower baselines.

      See Also
        ``<xfig_object>.justify'', ``<xfig_object>.get_bbox'',
        ``<xfig_object>.translate''

  2.18.  xfig_lookup_w3c_color (name)


      Synopsis
        Lookup an RGB value for an W3C color name

      Usage
        rgb = xfig_lookup_w3c_color (name)

      Description
        This function may be used to lookup the RGB value for a
        specified W3C color name. If the W3C rgb.txt file could not be
        loaded, or the color name does not exist within he file, NULL
        will be returned.

        The primary purpose of this function is to provide a mechanism
        for overriding Xfig color values with those defined by W3C.

      Example
        Xfig uses 0x00FF00 for green, whereas W3C defines 0x008000. Use
        the W3C value:


            xfig_new_color ("green", xfig_lookup_w3c_color ("green"));



      See Also
        ``xfig_new_color'', ``xfig_list_colors'',
        ``xfig_get_color_names''

  2.19.  xfig_make_font


      Synopsis
        Create a font structure used by SLxfig's LaTeX interface

      Usage
        Struct_Type xfig_make_font ([String_Type style, size, color])

      Qualifiers
        ; style: (default: "\bf\boldmath"R)
        ; size: (default: "\normalsize"R)
        ; color: (default: "black")

      Description
        If color is a string, it is considered to be a named color from
        the SLxfig color interface.  Alternatively, color can be an
        integer number, representing the color's RGB value.

        style, size, color arguments different from NULL overwrite
        qualifier values.

      See Also
        ``xfig_new_text''

  2.20.  xfig_meshgrid


      Synopsis
        Produce grid points for an image

      Usage
        (xx,yy) = xfig_meshgrid (xx, yy)

      Description
        This function takes two 1-d vectors representing the orthogonal
        grids for a rectangular region in the (x,y) plane and returns
        two 2-d arrays corresponding to the (x,y) coordinates of each
        intersecting grid point.

        Suppose that one wants to evaluate a function f(x,y) at each
        point defined by the two grid vectors. Simply calling f(x,y)
        using the grid vectors would lead to either a type-mismatch
        error or produce a 1-d result. The correct way to do this is to
        use the xfig_meshgrid function:


              result = f(xfig_meshgrid(x,y));



  2.21.  xfig_multiplot


      Synopsis
        Create a multiplot from individual panels that share the same x-
        axes

      Usage
        compound = xfig_multiplot (xfig_plot p1[], p2[], ...);

      Qualifiers
        ; cols=intval: number of columns (default: 1)
        ; title=strval: overall title on top of the multiplot
        ; xlabel=strval: overall xlabel below the multiplot
        ; x2label=strval: overall x2label on top of the multiplot
        ; ylabel=strval: overall ylabel left of the multiplot
        ; y2label=strval: overall y2label right of the multiplot
        ; align_ylabels=intval: bitmask for aligning all y{1,2}axis-
        labels (default: 1|2)

      Description
        p1, p2, ... can be single plot objects or arrays of them.
        xfig_multiplot arranges a multi-panel plot with cols columns.

        The plot windows are aligned in left-right, top-down order.
        xfig_multiplot switches off titles, axis- and ticmark labels of
        those plots for which those would overlap with other plots. It
        is thus be desirable to have common sizes of the plot windows,
        as well as common ranges and coordinate systems on adjoining
        axes.  This is particularly important if when more than one
        column is used.

        The return value is a compound object containing all plots in
        the multiplot (note that their number has to be a multiple of
        cols).  If the title or x(2)label qualifiers are specified and
        cols>1, additional text objects are added above and below the
        multiplot.  (For cols==1, the title/x(2)label of the first/last
        plot are set.)  The same holds for the y(2)label qualifiers, for
        which it depends on the resulting number of rows whether
        additional text is added on the left or right of the multiplot
        or whether the corresponding labels of the first or last plot
        are set (possibly overwritten).

  2.22.  xfig_new_color


      Synopsis
        Add a new color definition

      Usage
        xfig_new_color (name, RGB [,&id]

      Description
        This function may be used to add a new color called name with
        the specified RGB (24 bit integer) value. If the optional third
        parameter is provided, it must be a reference to a variable
        whose value upon return will be set to the integer index of the
        color.

      Notes
        Color names are converted to a canonical form by removing
        whitespace from the name and converting it to lowercase. This
        means that "OffWhite", "offwhite", and "off White" are all
        equivalent.

      See Also
        ``xfig_lookup_color_rgb'', ``xfig_lookup_color''

  2.23.  xfig_new_compound


      Synopsis
        Create an XFig compound list

      Usage
        c = xfig_new_compound ([obj1, obj2, ...]);

      Description
        An empty compound list is created with xfig_new_compound_list.
        All arguments passed to the xfig_new_compound function are
        inserted in the newly created list.

      See Also
        ``xfig_new_vbox_compound'', ``xfig_new_hbox_compound''

  2.24.  xfig_new_ellipse


      Synopsis
        Create a new ellipse object

      Usage
        XFig_Ellipse_Type xfig_create_ellipse (Double_Type a [, b])

      Qualifiers
        ; line: line style (default: 0)
        ; width: line width (default: 1)
        ; color: line color (default: -1)
        ; fillcolor: (default: -1)
        ; areafill: darkness or pattern (default: -1 or 20, depending on
        fillcolor)
        ; depth: XFig depth (default: 50)
        ; x0: x-position (default: 0)
        ; y0: y-position (default: 0)
        ; z0: z-position (default: 0)

  2.25.  xfig_new_eps


      Synopsis
        Create an SLxfig picture object from an eps file

      Usage
        obj = xfig_new_eps(String_Type filename);

      Qualifiers
        All qualifiers are passed to the xfig_new_pict function.

      See Also
        ``xfig_new_pict''

  2.26.  xfig_new_hbox_compound


      Synopsis
        Create an XFig compound list of horizontally aligned objects

      Usage
        c = xfig_new_hbox_compound (obj1, obj2 [, ...] [, space]);

      Description
        The objects obj2, ... are translated in negative y-direction
        such that all of them align horizontally according to their
        size.  If the last argument space is numeric, it indicates
        additional horizontal space that is inserted between each of the
        objects.

      Qualifiers
        ; just=val: Justifiy the objects with respect to the first.
        If val is 0 then the objects will be centered. If val is 1, the
        objects will be aligned at the top. If val is -1, they will be
        aligned at the bottom.  ; center: Center the objects with
        respect to the first

      See Also
        ``xfig_new_vbox_compound'', ``xfig_new_compound''

  2.27.  xfig_new_legend


      Synopsis
        Create a plot legend object

      Usage
        legend = xfig_new_legend (labels[], colors[], linestyles[],
        thicknesses[], width);

      Qualifiers
        ; areafill=intval: (default: 20)
        ; fillcolor=strval: (default: "white")
        ; labelsize=strval: (default: "large")

      Description
        The xfig_new_legend function creates a legend object suitable
        for adding to a plot. The legend will consist of ...

  2.28.  xfig_new_pict


      Synopsis
        Create an object that encapsulates an image file

      Usage
        obj = xfig_new_pict(filename, width, height [; qualifiers])

      Description
        This function creates an object containing the specified image
        file and scales it to the specified width an height. The
        resulting object containing the image will be centered at
        (0,0,0).

      Qualifiers
        ; depth: XFig depth
        ; x0: x-position (default: 0)
        ; y0: y-position (default: 0)
        ; z0: z-position (default: 0)
        ; just=[jx,jy]: justification (default: [0,0])
        The just qualifier may be used to indicate how the object is to
        be justified with respect to the origin. Its value must be a 2d
        numeric array [dx,dy] that gives the offset of the center of the
        image scaled with respect to the bounding box. Examples include:


              just=[0,0]           Center object upon the origin (default)
              just=[-0.5,-0.5]     Put the lower-left corner at the origin
              just=[0.5,-0.5]      Put the lower-right corner at the origin
              just=[0.5,0.5]       Put the upper-right corner at the origin
              just=[-0.5,-0.5]     Put the upper-left corner at the origin



      See Also
        ``xfig_new_text'', ``xfig_justify_object''

  2.29.  xfig_new_png


      Synopsis
        Create an object that encapsulates a png image

      Usage
        obj = xfig_new_png(String_Type filename);

      Qualifiers
        ; depth: XFig depth
        ; x0: x-position (default: 0)
        ; y0: y-position (default: 0)
        ; z0: z-position (default: 0)
        ; just=[jx,jy]: justification (default: [0,0])

      Description
        xfig_new_png reads the image dimensions from the file header and
        passes them to xfig_new_pict. See its documentation for a
        detailed description of the qualifiers.

      See Also
        ``xfig_new_pict''

  2.30.  xfig_new_polyline


      Synopsis
        Create a new polyline object

      Usage
        p = xfig_new_polyline(Vector_Type X);
        % or
        p = xfig_new_polyline(Array_Type x [, y [, z]]);

      Description
        If xfig_new_polyline is called with one Vector_Type argument X,
        the fields x, y, and z are expected to contain coordinate arrays
        of the polyline's vertices.  These can also be specified
        directly as Array_Type arguements; all unspecified coordinates
        are set to zero.

      Qualifiers
        ; closed: closes the polygon by repeating the first vertex at
        the end
        ; line: line style
        ; width: line width
        ; color: line color
        ; fillcolor: color to fill the region inside the polyline object
        ; areafill: darkness or pattern (default: 20)
        ; depth: Xfig depth
        ; join: shape of the vertex of lines: MITER, ROUNDED, BEVEL
        ; cap: shape of end points of lines: BUTT, ROUND, PROJECTING)
        ; forward_arrow: see documentation of xfig_create_arrow
        ; backward_arrow: see documentation of xfig_create_arrow

      See Also
        ``xfig_create_arrow''

  2.31.  xfig_new_text


      Synopsis
        Create a text object by running LaTeX

      Usage
        obj = xfig_new_text (String_Type text [,font_object])

      Qualifiers
        ; extra_packages: NULL
        ; preamble: (default: NULL)
        ; color=strval: (default: "black")
        ; style=strval: (default: "\bf\boldmath"R)
        ; size=strval: (default: "\normalsize"R)
        ; rotate=angle: rotate text by angle in degrees (default: 0)
        ; dvi2eps_method:
        ; x0: x-position (default: 0)
        ; y0: y-position (default: 0)
        ; z0: z-position (default: 0)
        ; depth: Xfig depth
        ; just=[jx,jy]: justification, see xfig_new_pict (default:
        [0,0])

      Description
        This function runs LaTeX on the specified text string and
        returns the resulting object. The text string must be formatted
        according to the LaTeX rules. The optional parameter is a
        structure that may be used to specify the font, color,
        pointsize, etc to use when calling LaTeX. This structure may be
        instantiated using the xfig_make_font.

      See Also
        ``xfig_make_font'', ``xfig_add_latex_package'',
        ``xfig_set_latex_preamble'', ``xfig_new_pict''

  2.32.  xfig_new_vbox_compound


      Synopsis
        Create an XFig compound list of vertically aligned objects

      Usage
        c = xfig_new_vbox_compound (obj1, obj2 [, ...] [, space]);

      Description
        The objects obj2, ... are translated in negative y-direction
        such that all of them align vertically according to their size.
        If the last argument space is numeric, it indicates additional
        vertical space that is inserted between each of the objects.

      Qualifiers
        ; just=val: Justifiy the objects with respect to the first.
        If val is 0 then the objects will be centered. If val is -1, the
        objects will be left justified. If val is +1, they will be right
        justified.  ; center: Center the objects with respect to the
        first

      See Also
        ``xfig_new_hbox_compound'', ``xfig_new_compound''

  2.33.  xfig_pict.scale


      Synopsis
        Scale an xfig pict object

      Usage
        xfig_pict.scale (s);
        % or
        xfig_pict.scale (sx, sy);

      See Also
        ``xfig_new_pict''

  2.34.  xfig_plot--errorbars


      Qualifiers
        ; eb_line=intval: line style for error bars (default: line
        qualifier)
        ; eb_color=intval: color of error bars (default: color
        qualifier)
        ; eb_width=intval: thickness of error bars (default: width
        qualifier)
        ; eb_depth=intval: Xfig depth of error bars (default: depth
        qualifier)
        ; [x,y]eb_factor=intval: terminal size of error bars (default:
        0)
        ; [x,y]min_max: Asymmetric error bars are already min/max
        values.

      Description
        Asymmetric error bars are specified as lists of negative and
        positive errors.  If the min_max qualifier (or the appropriate
        {x,y}min_max qualifier) is set, then the elements of the list
        are considered as minimum and maximum values.

      Example


            variable xfig_plot = xfig_plot_new();
            xfig_plot.world(0, 10, 0, 10);
            xfig_plot.plot(1, 5,          1    ; sym="x");           % y = 5 (+-1)
            xfig_plot.plot(3, 5,         {2, 3}; sym="x");           % y = 5 (+3)(-2)
            xfig_plot.plot(5, 5,         {3, 8}; sym="x",  minmax);  % y = 5 [3...8] (same as above)
            xfig_plot.plot(7, 5, {1, 2}, {3, 8}; sym="x", yminmax);  % x = 8 (+1)(-2),  but y = 5 [3...8]



      See Also
        ``xfig_plot.plot'', ``xfig_plot.hplot''

  2.35.  xfig_plot--initialize_plot


      Synopsis
        Qualifiers to initialize the axes of an xfig_plot object:

      Qualifiers
        ; xlog: use a logarithmic x-axis
        ; ylog: use a logarithmic y-axis
        ; loglog: use logarithmic axes
        ; padx: [=0.05]: fraction of xrange to be padded on both sides
        ; pady: [=0.05]: fraction of xrange to be padded on both sides

      Description
        The world coordinate system of an xfig_plot object are
        initialized through the following functions, unless they are
        already set before:

      See Also
        ``xfig_plot.plot'', ``xfig_plot.hplot'', ``xfig_plot.plot_png'',
        ``xfig_plot.plot_pict'', ``xfig_plot.shade_region''

  2.36.  xfig_plot--wcs


      Synopsis
        Qualifiers to specify a plot's world coordinate system

      Qualifiers
        ; world0: use device coordinates for x- and y-axes
        ; world1: use first coordinate system for x- and y-axes
        ; world2: use second coordinate system for x- and y-axes
        ; world{a}{b}: use a-th WCS for x-axis and b-th WCS for y-axis,
        where 0 <= a, b <= 2

      Description
        If none of these qualifiers is specified, world1 is assumed.

        Device coordinates (0th WCS) run from 0 to 1 along the
        corresponding axis.

        The first or second coordinate system (1st or 2nd WCS) can be
        defined with the .world(1) or .world(2) methods. (If not set
        before, they are set automatically by some plot functions, see
        xfig_plot--initialize_plot.)

        The WCS qualifiers apply to the following functions:
        xfig_plot.plot, xfig_plot.hplot, xfig_plot.shade_region,
        xfig_plot.add_object, xfig_plot.xylabel, xfig_plot.get_world,
        xfig_plot.xfig_coords

      See Also
        ``xfig_plot.world'', ``xfig_plot.world1'', ``xfig_plot.world2'',
        ``xfig_plot--initialize_plot''

  2.37.  xfig_plot.add_object


      Synopsis
        Add an object to a plot at a world coordinate position

      Usage
        xfig_plot.add_object (obj[, x, y[, dx, dy]]);

      Qualifiers
        % qualifiers to specifiy the world coordinate system, see
        xfig_plot--wcs

      Description
        This function may be used to add an object to a plot window at a
        specified world coordinate. The dx and dy arguments control the
        justification of the object. The values of these parameters are
        offsets relative to the size of the object, and as such
        ordinarily have values in the interval [-0.5,0.5]. For example,
        0,0 will center the object on (x,y), and (-0.5,-0.5) will move
        the lower left corner of the object to the specified coordinate.

      See Also
        ``xfig_plot--wcs''

  2.38.  xfig_plot.axis


      Usage
        xfig_plot.axis([; qualifiers]);

      Qualifiers
        ; on: draw axis, major and minor tic marks, as well as tic
        labels (default: on)
        ; off: do not draw axis, major nor minor tic marks, nor tic
        labels
        ; linear: set linear axis scale
        ; log: set logarithmic axis scale
        ; major: draw major tic marks [precedence over on/off] or array
        of major tic mark values
        ; minor: draw minor tic marks [precedence over on/off] or array
        of minor tic mark values
        ; color: color of axis, major and minor tic marks
        ; major_color: color of major tic marks [precedence over color]
        ; minor_color: color of minor tic marks [precedence over color]
        ; width: width of axis, major and minor tic marks
        ; major_width: width of major tic marks [precedence over width]
        ; minor_width: width of minor tic marks [precedence over width]
        ; line: line style of axis, major and minor tic marks
        ; major_line: line style of major tic marks [precedence over
        line]
        ; minor_line: line style of minor tic marks [precedence over
        line]
        ; major_len: length of the major tic marks
        ; minor_len: length of the minor tic marks
        ; grid: extend major and minor tic marks to a grid
        ; major_grid: extend major tic marks to a grid [precedence over
        grid]
        ; minor_grid: extend minor tic marks to a grid [precedence over
        grid]
        ; depth: Xfig depth of the axis
        ; tic_depth: Xfig depth of the ticmarks
        ; maxtics: maximum number of major tic marks
        ; ticlabels: draw tic labels (requires major tic marks)
        ; ticlabels_confine: prevent tic labels from overhanging the
        plot box
        ; ticlabel_style: tic label font style, see xfig_make_font
        ; ticlabel_color: tic label font color, see xfig_make_font
        ; ticlabel_size: tic label font size, see xfig_make_font
        ; format: tic label format string in `sprintf' style
        ; wcs: name of a custom world coordinate system transformation

      Description
        All axes can be configured with the qualifiers mentioned above.

      See Also
        ``xfig_plot.xaxis'', ``xfig_plot.x1axis'', ``xfig_plot.x2axis'',
        ``xfig_plot.yaxis'', ``xfig_plot.y1axis'', ``xfig_plot.y2axis''

  2.39.  xfig_plot.get_world


      Synopsis
        Get the world coordinates of a plot

      Usage
        [xmin,xmax,ymin,ymax] = xfig_plot.get_world ();

      Qualifiers
        % qualifiers to specifiy the world coordinate system

      See Also
        ``xfig_plot--wcs''

  2.40.  xfig_plot.hplot


      Usage
        xfig_plot.hplot ([x,] y);
        % or
        xfig_plot.hplot (x, y[, dy]);

      Qualifiers
        % qualifiers to initialize the first plot only, see
        xfig_plot--initialize_plot

        % qualifiers to specifiy the world coordinate system, see
        xfig_plot--wcs

        % qualifiers for lines (defaults for error bars): ; width: line
        thickness
        ; color: line color
        ; line: line style
        ; fillcolor=fcol: fill histogram with color fcol (default:
        color)
        ; fill[=area_fill]: use style area_fill for shaded histogram
        (default: 20, if set)
        ; depth: Xfig depth

        % qualifiers for error bars: see xfig_plot--errorbars

        % qualifiers for histogram: ; y_first: y-value of first bin's
        vertical line
        ; y_last: y-value of last bin's vertical line

      Description
        x is an array of lower bin boundaries corresponding to the
        histogram values y. If length(x)==length(y)+1, then x[-1] is the
        upper boundary of the last bin, otherwise, the last bin will be
        as large as the previous one.  If no x values are given, x =
        [1:length(y)] is assumed.

      See Also
        ``xfig_plot--initialize_plot'', ``xfig_plot--wcs'',
        ``xfig_plot--errorbars''

  2.41.  xfig_plot.plot


      Usage
        xfig_plot.plot ([x,] y);
        % or
        xfig_plot.plot (x, y, [dx,] dy);

      Qualifiers
        % qualifiers to initialize the first plot only, see
        xfig_plot--initialize_plot

        % qualifiers to specifiy the world coordinate system, see
        xfig_plot--wcs

        % qualifiers for lines (defaults for error bars and symbols): ;
        color=strval: color of lines symbols and error bars
        ; width=intval: thickness of lines and error bars
        ; depth=intval: Xfig depth
        ; line=intval: line style for lines and error bars
        ; forward_arrow: see xfig_create_arrow (default: NULL)
        ; backward_arrow: see xfig_create_arrow (default: NULL)

        % qualifiers for error bars: see xfig_plot--errorbars

        % qualifiers for symbols: ; sym=strval: symbol, see
        xfig_plot_get_symbol_names
        ; symcolor=strval: color of symbols (default: color qualifier)
        ; size=val: symbol point size
        ; fill[=intval]: area fill style (default: 20, if set; otherwise
        -1)
        ; fillcolor=strval: color for filled symbols
        ; symlinestyle=intval: line style to draw symbols
        ; symwidth=intval: thickness of symbol lines (default: width
        qualifier)
        ; symdepth=intval: Xfig depth of symbols (default: depth
        qualifier)

      Description
        If no x values are given, x = [1:length(y)] is assumed.  If a
        symbol is specified, no lines are drawn unless the line
        qualifier is also specified.

      See Also
        ``xfig_plot--initialize_plot'', ``xfig_plot--wcs'',
        ``xfig_plot--errorbars''

  2.42.  xfig_plot.plot_pict


      Usage
        xfig_plot.plot_pict (String_Type imgfile);

      Qualifiers
        ; depth: Xfig depth

        % qualifiers to initialize the first plot only, see
        xfig_plot--initialize_plot

      See Also
        ``xfig_plot.plot_png''

  2.43.  xfig_plot.plot_png


      Synopsis
        Add a png file to a plot, scaling it to the window

      Usage
        xfig_plot.plot_png (String_Type pngfile);
        % or
        xfig_plot.plot_png (Array_Type image);

      Qualifiers
        ; depth: Xfig depth

        % qualifiers to initialize the first plot only, see
        xfig_plot--initialize_plot ; cmap: name of the color map used by
        png_gray_to_rgb

      Description
        The image from pngfile is drawn in the plot region.

        If a two-dimensional array image is passed to .plot_png, it is
        converted to a png file in the temporary directory, using the
        png_gray_to_rgb function and possibly a color map.  All other
        qualifiers are forwarded to png_gray_to_rgb.

      See Also
        ``xfig_plot_new_png'', ``xfig_plot.plot_pict'',
        ``xfig_set_tmp_dir'', ``png_gray_to_rgb''

  2.44.  xfig_plot.shade_region


      Synopsis
        Add a filled rectangle or polygon to the plot

      Usage
        xfig_plot.shade_region (x[], y[]);
        % or
        xfig_plot.shade_region (xmin, xmax, ymin, ymax);

      Qualifiers
        % qualifiers to initialize the first plot only see
        xfig_plot--initialize_plot

        % qualifiers to specifiy the world coordinate system see
        xfig_plot--wcs

        ; line: line style
        ; width: line thickness
        ; color: line color
        ; fillcolor: fill color (default: color)
        ; fill: area fill style (default: 20)
        ; depth: Xfig depth of shaded region

      See Also
        ``xfig_plot--initialize_plot'', ``xfig_plot--wcs''

  2.45.  xfig_plot.title


      Synopsis
        Add a title to a plot

      Usage
        xfig_plot.title (String_Type title);
        % or
        xfig_plot.title (XFig_Object title);

      Description
        The title is created from the string with the xfig_new_text
        function using all applied qualifiers.  If title is no string,
        it is assumed to be an already properly formatted xfig object.
        The title is centered above the plot area.  Any previously
        existing title object is removed.

  2.46.  xfig_plot.world


      Synopsis
        define a plot's world coordinate system

      Usage
        xfig_plot.world (Double_Type xdata[], ydata[]);
        % or
        xfig_plot.world (Double_Type x0, x1, y0, y1);

      Qualifiers
        ; xlog: use a logarithmic x-axis
        ; ylog: use a logarithmic y-axis
        ; loglog: use logarithmic axes
        ; padx: fraction of xrange to be padded on both sides (default:
        0.05 or 0)
        ; pady: fraction of yrange to be padded on both sides (default:
        0.05 or 0)

      See Also
        ``xfig_plot.world1'', ``xfig_plot.world2''

  2.47.  xfig_plot.world1


      Synopsis
        define a plot's first world coordinate system

      See Also
        ``xfig_plot.world''

  2.48.  xfig_plot.world2


      Synopsis
        define a plot's second world coordinate system

      Qualifiers
        ; xticlabels: flag whether (1) or not (0) to draw ticlabels on
        x2axis (default: 1)
        ; yticlabels: flag whether (1) or not (0) to draw ticlabels on
        y2axis (default: 1)

      See Also
        ``xfig_plot.world''

  2.49.  xfig_plot.x1axis


      Usage
        xfig_plot.x1axis([; qualifiers]);

      Description
        This method allows for the configuration of the first x-axis via
        qualifiers -- see xfig_plot.axis for further information.

      See Also
        ``xfig_plot.axis''

  2.50.  xfig_plot.x2axis


      Usage
        xfig_plot.x2axis([; qualifiers]);

      Description
        This method allows for the configuration of the second x-axis
        via qualifiers -- see xfig_plot.axis for further information.

      See Also
        ``xfig_plot.axis''

  2.51.  xfig_plot.x2label


      Synopsis
        Add a label for the second x-axis to a plot

      Usage
        xfig_plot.x2label (String_Type x2label);

      Description
        The x2label is created from the string with the xfig_new_text
        function using all applied qualifiers.

      See Also
        ``xfig_new_text''

  2.52.  xfig_plot.xaxis


      Usage
        xfig_plot.xaxis([; qualifiers]);

      Qualifiers
        ; ticlabels1: overwrites the ticlabels qualifier for the x1axis
        ; ticlabels2: overwrites the ticlabels qualifier for the x2axis

      Description
        This method allows for the configuration of both x-axes via
        qualifiers -- see xfig_plot.axis for further information.

      See Also
        ``xfig_plot.axis''

  2.53.  xfig_plot.xfig_coords


      Usage
        (Double_Type xXfig, yXfig) = xfig_plot.xfig_coords (Double_Type
        x, y);
        % or
        Double_Type xXfig = xfig_plot.xfig_coords (Double_Type x, );
        % or
        Double_Type yXfig = xfig_plot.xfig_coords (, Double_Type y);

      Qualifiers
        % qualifiers to specify the world coordinate system,

      See Also
        ``xfig_plot--wcs''

  2.54.  xfig_plot.xlabel


      Synopsis
        Add an x-axis label to a plot

      Usage
        xfig_plot.xlabel (String_Type xlabel);

      Description
        The x-label is created from the string with the xfig_new_text
        function using all applied qualifiers.

      See Also
        ``xfig_new_text''

  2.55.  xfig_plot.xylabel


      Usage
        xfig_plot.xylabel (Double_Type x, y, String_Type text[, dx,
        dy]);

      Qualifiers
        % qualifiers to specifiy the world coordinate system, see
        xfig_plot--wcs

      See Also
        ``xfig_plot_text'', ``xfig_plot--wcs''

  2.56.  xfig_plot.y1axis


      Usage
        xfig_plot.y1axis([; qualifiers]);

      Description
        This method allows for the configuration of the first y-axis via
        qualifiers -- see xfig_plot.axis for further information.

      See Also
        ``xfig_plot.axis''

  2.57.  xfig_plot.y2axis


      Usage
        xfig_plot.y2axis([; qualifiers]);

      Description
        This method allows for the configuration of the second y-axis
        via qualifiers -- see xfig_plot.axis for further information.

      See Also
        ``xfig_plot.axis''

  2.58.  xfig_plot.y2label


      Synopsis
        Add a label for the second y-axis to a plot

      Usage
        xfig_plot.y2label (String_Type y2label);

      Description
        The y2label is created from the string with the xfig_new_text
        function using all applied qualifiers.

      See Also
        ``xfig_new_text''

  2.59.  xfig_plot.yaxis


      Usage
        xfig_plot.yaxis([; qualifiers]);

      Qualifiers
        ; ticlabels1: overwrites the ticlabels qualifier for the y1axis
        ; ticlabels2: overwrites the ticlabels qualifier for the y2axis

      Description
        This method allows for the configuration of both y-axes via
        qualifiers -- see xfig_plot.axis for further information.

      See Also
        ``xfig_plot.axis''

  2.60.  xfig_plot.ylabel


      Synopsis
        Add a y-axis label to a plot

      Usage
        xfig_plot.ylabel (String_Type ylabel);

      Description
        The ylabel is created from the string with the xfig_new_text
        function using all applied qualifiers.

      See Also
        ``xfig_new_text''

  2.61.  xfig_plot_add_symbol


      Synopsis
        Add a plot symbol

      Usage
        xfig_plot_add_symbol (String_Type name, Ref_Type funct)

      Description
        This function may be used to add a new plot symbol of the
        specified name.  The funct parameter specifies a function to be
        called to create the symbol. It will be called with a single
        parameter: a value representing the scale size of the symbol in
        fig units. The function must return two arrays representing the
        X and Y coordinates of the polygons that represent the symbol.
        The center of the object is taken to be (0,0). If more than one
        polygon is required to represent the object, an array of arrays
        may be returned.

  2.62.  xfig_plot_add_transform


      Usage
        xfig_plot_add_transform (String_Type name, Ref_Type &wcs_func,
        &wcs_invfunc, Any_Type client_data);

      Qualifiers
        ; xmin: (default: -inf)
        ; xmax: (default: +inf)
        ; ticfun: (default: &generic_compute_tics)

      Description
        wcs_func (wcs_invfunc) is a function of two arguments: the world
        (plot) coordinate and some client data.  It has to return the
        correspondig plot (world) coordinate.

        The qualifier ticfun may reference a function that takes 4
        arguments: xmin, xmax, maxtics, and client_data.  It is supposed
        to return two arrays of major and minor tic marks.

  2.63.  xfig_plot_get_symbol_names


      Usage
        String_Type[] xfig_plot_get_symbol_names ()

      See Also
        ``xfig_plot.plot''

  2.64.  xfig_plot_new


      Synopsis
        Create a new plot object

      Usage
        w = xfig_plot_new ( [Int_Type width, Int_Type height] );

      Description
        This function creates a new plot object of the specified width
        and height.  If the width and height parameters are not given,
        defaults will be used.  The width and height values specify the
        size of the plotting area and do not include the space for tic
        marks and labels.

        The following qualifiers configure all axes' tic labels at once:

      Qualifiers
        ; ticlabel_style: tic label font style, see xfig_make_font
        ; ticlabel_color: tic label font color, see xfig_make_font
        ; ticlabel_size: tic label font size, see xfig_make_font

      Example


             w = xfig_plot_new ();



      See Also
        ``xfig_plot_define_world'', ``xfig_render_object''

  2.65.  xfig_plot_new_png


      Synopsis
        Create a new plot window for a png file

      Usage
        w = xfig_plot_new_png (file)

      Qualifiers
        ; depth: Xfig depth

      See Also
        ``xfig_plot_new'', ``xfig_plot.plot_png'',
        ``xfig_plot.plot_pict''

  2.66.  xfig_plot_text


      Synopsis
        Add text to the plot

      Usage
        xfig_plot_text (w, text, x, y [,dx, dy])


                  w: plot object
               x, y: world coordinates
             dx, dy: justification



      Description
        This function creates a text object at the specified location on
        the plot.  By default, the text will be centered on the
        specified world coordinates.  The justification parameters dx
        and dy may be used to specify the justifcation of the text. See
        the documentation for xfig_plot_add_object for more information.

      Example


             xfig_plot_text (w, "$cos(\omega t)$"R, 3.2, 6.0, -0.5, 0);



     will left justify the text at the position (3.2,6.0).

      See Also
        ``xfig_plot_add_object'', ``xfig_new_text''

  2.67.  xfig_render_object


      Synopsis
        Render an object to a device

      Usage
        xfig_render_object (obj, device)

      Description
        This function renders the specified object to a specified
        device.  If the device parameter is a string, then a device will
        be opened with the specified name.

      See Also
        ``xfig_create_file'', ``xfig_close_file''

  2.68.  xfig_set_eye


      Synopsis
        Define the point from which the projection of 3d space is seen

      Usage
        xfig_set_eye (Double_Type dist, theta, phi [, roll]);

      Description
        dist - distance of the eye from the focus theta - polar angle
        from the z-axis (in degrees) phi - azimuthal angle in the x-y-
        plane (in degrees) roll - roll angle (in degrees)

      See Also
        ``xfig_get_eye'', ``xfig_get_eye_roll'', ``xfig_set_eye_roll'',
        ``xfig_set_focus''

  2.69.  xfig_set_eye_roll


      Synopsis
        Set the roll angle under which the projection of 3d space is
        seen

      Usage
        xfig_get_eye_roll (Double_Type roll);

      Description
        The roll angle is measured in degrees.

      See Also
        ``xfig_get_eye_roll'', ``xfig_set_eye'', ``xfig_set_focus''

  2.70.  xfig_set_focus


      Synopsis
        Define the focus point of the projection of 3d space

      Usage
        xfig_set_focus (Vector_Type X);

      See Also
        ``xfig_get_focus'', ``xfig_set_eye''

  2.71.  xfig_set_font_style


      Synopsis
        Set the default font style for LaTeX

      Usage
        xfig_set_font_style (String_Type style);

      Description
        Unless changed, the default font style is "\bf\boldmath"R.

      See Also
        ``xfig_make_font'', ``xfig_new_text'',
        ``xfig_add_latex_package''

  2.72.  xfig_set_latex_preamble


      Usage
        xfig_set_latex_preamble (String_Type preamble)

      See Also
        ``xfig_get_latex_preamble''

  2.73.  xfig_set_output_driver


      Synopsis
        Associate an output driver to a file extension

      Usage
        xfig_set_output_driver (String_Type ext, String_Type cmd)

      Description
        This may may be used to define the command that runs to created
        the specified output format (dictated by the extension) from the
        corresponding .fig file.  The ext parameter specifies the
        filename extension and cmd is the shell command that will be
        used to generate the file.

        The cmd may contain the following format descriptors that will
        be replaced by the corresponding objects before being passed to
        the shell:


             %I    Input .fig file
             %O    Output file
             %P    paper-size
             %B    basename of the file



      Example
        The default driver for postscript output is given by:


            xfig_set_output_driver ("ps", "fig2dev -L ps -c -z %P %I %O");



     The ps2ps command may result in a smaller file size at a slight
     cost of resolution. It may be used as follows:


              xfig_set_output_driver ("ps", "fig2dev -L ps -c -z %P %I %B-tmp.ps"
                                       + ";ps2ps %B-tmp.ps %O; rm -f %B-tmp.ps");



      See Also
        ``xfig_set_paper_size''

  2.74.  xfig_set_verbose


      Synopsis
        Control the level of chattiness

      Usage
        xfig_set_verbose(Integer_Type level);

      Description
        This function may be used to control the verbosity level of the
        xfig functions that display informational messages.

      Notes
        It is not always possible to control the verbosity level of
        external programs. For the LaTeX/eps interface, if the level is
        0, then only the running command will be displayed and any
        output will be redirected to /dev/null. Otherwise if level > 0,
        then the output will not be redirected.



