grid.curve               package:grid               R Documentation

_D_r_a_w _a _C_u_r_v_e _B_e_t_w_e_e_n _L_o_c_a_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     These functions create and draw a curve from one location to
     another.

_U_s_a_g_e:

     grid.curve(...)
     curveGrob(x1, y1, x2, y2, default.units = "npc",
               curvature = 1, angle = 90, ncp = 1, shape = 0.5,
               square = TRUE, squareShape = 1, 
               inflect = FALSE, arrow = NULL, open = TRUE,
               debug = FALSE,
               name = NULL, gp = gpar(), vp = NULL)
     arcCurvature(theta)

_A_r_g_u_m_e_n_t_s:

      x1: A numeric vector or unit object specifying the x-location of
          the start point.

      y1: A numeric vector or unit object specifying the y-location of
          the start point.

      x2: A numeric vector or unit object specifying the x-location of
          the end point.

      y2: A numeric vector or unit object specifying the y-location of
          the end point.

default.units: A string indicating the default units to use if 'x1',
          'y1', 'x2' or 'y2' are only given as numeric values.

curvature: A numeric value giving the amount of curvature. Negative
          values produce left-hand curves, positive values produce
          right-hand curves, and zero produces a straight line.

   angle: A numeric value between 0 and 180, giving an amount to skew
          the control points of the curve.  Values less than 90 skew
          the curve towards the start point and values greater than 90
          skew the curve towards the end point.

     ncp: The number of control points used to draw the curve. More
          control points creates a smoother curve.

   shape: A numeric vector of values between -1 and 1, which control
          the shape of the curve relative to its control points. See
          'grid.xspline' for more details.

  square: A logical value that controls whether control points for the
          curve are created city-block fashion or obliquely.  When
          'ncp' is 1 and 'angle' is 90, this is typically 'TRUE',
          otherwise this should probably be set to 'FALSE' (see
          Examples below).

squareShape: A 'shape' value to control the behaviour of the curve
          relative to any additional control point that is inserted if
          'square' is 'TRUE'.

 inflect: A logical value specifying whether the curve should be cut in
          half and inverted (see Examples below).

   arrow: A list describing arrow heads to place at either end of the
          curve, as produced by the 'arrow' function.

    open: A logical value indicating whether to close the curve
          (connect the start and end points).

   debug: A logical value indicating whether debugging information
          should be drawn.

    name: A character identifier. 

      gp: An object of class 'gpar', typically the output from a call
          to the function 'gpar'.  This is basically a list of
          graphical parameter settings.

      vp: A Grid viewport object (or NULL).

     ...: Arguments to be passed to 'curveGrob'.

   theta: An angle (in degrees).

_D_e_t_a_i_l_s:

     Both functions create a curve grob (a graphical object describing
     an curve), but only 'grid.curve' draws the curve.

     The 'arcCurvature' function can be used to calculate a 'curvature'
     such that control points are generated on an arc corresponding to
     angle 'theta'.  This is typically used in conjunction with a large
     'ncp' to produce a curve corresponding to the desired arc.

_V_a_l_u_e:

     A grob object.

_S_e_e _A_l_s_o:

     Grid, 'viewport', 'grid.xspline', 'arrow'

_E_x_a_m_p_l_e_s:

     curveTest <- function(i, j, ...) {
       pushViewport(viewport(layout.pos.col=j, layout.pos.row=i))
       do.call("grid.curve", c(list(x1=.25, y1=.25, x2=.75, y2=.75),
               if (is.null(...)) NULL else list(...)))
       grid.text(sub("list", "", deparse(substitute(list(...)))),
                 y=unit(1, "npc"))
       popViewport()
     }
     # grid.newpage()
     pushViewport(plotViewport(c(0, 0, 1, 0),
                               layout=grid.layout(2, 1, heights=c(2, 1))))
     pushViewport(viewport(layout.pos.row=1,
                           layout=grid.layout(3, 3, respect=TRUE)))
     curveTest(1, 1, NULL)
     curveTest(1, 2, inflect=TRUE)
     curveTest(1, 3, angle=135)
     curveTest(2, 1, arrow=arrow())
     curveTest(2, 2, ncp=8)
     curveTest(2, 3, shape=0)
     curveTest(3, 1, curvature=-1)
     curveTest(3, 2, square=FALSE)
     curveTest(3, 3, debug=TRUE)
     popViewport()
     pushViewport(viewport(layout.pos.row=2,
                           layout=grid.layout(3, 3)))
     curveTest(1, 1, NULL)
     curveTest(1, 2, inflect=TRUE)
     curveTest(1, 3, angle=135)
     curveTest(2, 1, arrow=arrow())
     curveTest(2, 2, ncp=8)
     curveTest(2, 3, shape=0)
     curveTest(3, 1, curvature=-1)
     curveTest(3, 2, square=FALSE)
     curveTest(3, 3, debug=TRUE)
     popViewport(2)