pst-bspline 1.44 (20aug11)

git-svn-id: svn://tug.org/texlive/trunk@23622 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 81 insertions, 18 deletions

diff --git a/Master/texmf-dist/doc/generic/pst-bspline/README b/Master/texmf-dist/doc/generic/pst-bspline/README
index 62d5a1ef35c..4488857fb91 100644
--- a/Master/texmf-dist/doc/generic/pst-bspline/README
+++ b/Master/texmf-dist/doc/generic/pst-bspline/README
@@ -2,10 +2,10 @@
 %%
 %% Michael Sharpe <msharpe@ucsd.edu>
 %%
-%% Version 1.44, 2011/07/30
+%% Version 1.44, 2011/08/19
 %%
 %% License: Free
 
-This package draws uniform, cubic B-spline curves, open and closed, based on a sequence of B-spline control points. There is also code which permits drawing the open or closed cubic B-spline curve interpolating a sequence of points. This update adds a number of macros allowing B-spline curves to be used as if they were parametric curves.
+This package draws uniform, cubic B-spline curves, open and closed, based on a sequence of B-spline control points. There is also code which permits drawing the open or closed cubic B-spline curve interpolating a sequence of points. This update adds a number of macros allowing B-spline curves to be used as if they were parametric curves or graphs of functions.
 
 The .tex and .sty files should be installed in a folder searched by TeX. All documentation is in pst-bspline-doc.pdf.
\ No newline at end of file
diff --git a/Master/texmf-dist/doc/generic/pst-bspline/pst-bspline-doc.pdf b/Master/texmf-dist/doc/generic/pst-bspline/pst-bspline-doc.pdf
index f8392d5358c..5aea67e4329 100644
--- a/Master/texmf-dist/doc/generic/pst-bspline/pst-bspline-doc.pdf
+++ b/Master/texmf-dist/doc/generic/pst-bspline/pst-bspline-doc.pdf
diff --git a/Master/texmf-dist/doc/generic/pst-bspline/pst-bspline-doc.tex b/Master/texmf-dist/doc/generic/pst-bspline/pst-bspline-doc.tex
index d88db518937..235522f7950 100644
--- a/Master/texmf-dist/doc/generic/pst-bspline/pst-bspline-doc.tex
+++ b/Master/texmf-dist/doc/generic/pst-bspline/pst-bspline-doc.tex
@@ -1,5 +1,4 @@
-\listfiles
-\documentclass[dvips,11pt]{article}
+\documentclass[dvips,11pt]{amsart}
 \usepackage{amsmath}
 \usepackage{amsthm} 
 \usepackage{graphicx}
@@ -38,20 +37,20 @@ I'll focus on two special cases: (i) relaxed, uniform B-splines; (ii) periodic,
  draws the relaxed, uniform B-spline interpolating the specified points.
 \item[\cs{psBspline}(1,1)(3,0)(5,2)(4,5)] draws the relaxed, uniform B-spline with specified control points.
 \item[\cs{psBspline}\{B\}(1,1)(3,0)(5,2)(4,5)] draws the relaxed, uniform B-spline with specified control points, using \texttt{B} as basename for the constructed points.
-\item[\cs{psBsplineE}(1,1)(3,0)(5,2)(4,5)] is the same as \cs{psBspline}(1,1)(3,0)(5,2)(4,5) except that it omits the first and last segments.
+\item[\cs{psBsplineE}(1,1)(3,0)(5,2)(4,5)] has the same effect as the command \cs{psBspline}(1,1)(3,0)(5,2)(4,5) except that it omits the first and last segments.
 \item[\cs{psBsplineC}(1,1)(3,0)(5,2)(4,5)] extends the specified points periodically, drawing a closed curve with the specified points as control points.
 \item[\cs{psBsplineNodes}\{B\}\{4\}] draws the relaxed, uniform B-spline with control points \texttt{B0}..{\tt B4}.
 \item[\cs{psBsplineNodesE}\{B\}\{4\}] is the same as \cs{psBsplineNodes}\{B\}\{4\} except that it omits the first and last segments.
 \item[\cs{psBsplineNodesC}\{B\}\{4\}] extends the node sequence periodically, drawing a closed curve with them as control points.
 \item[\cs{beztobsp}(1,2)(-3,-4)(5,6)(-7,-8)\{B\}] creates nodes {\tt B0}..{\tt B3} for which the curve \cs{psBsplineNodesE}\{B\}\{3\} is identical to the B\'ezier curve determined by the specified points. (It does not draw the curve.)
-\item[\cs{bspcurvepoints\{B\}\{5\}\{P\}}] creates PostScript arrays to describe a sequence of points along the curve that would be the result of the command  \cs{psBsplineNodes}\{B\}\{5\}, naming those arrays {\tt P.X}, {\tt P.Y} (for position), {\tt PNormal.X}, {\tt PNormal.Y}, {\tt PDelta.X} and {\tt PDelta.Y}. (Nothing is drawn.)
-\item[\cs{bspcurvepointsE\{B\}\{5\}\{P\}}] does the same as \cs{bspcurvepoints}, but omits the first and last segments. (Nothing is drawn.)
+\item[\cs{bspcurvepoints\{B\}\{5\}\{P\}}] creates PostScript arrays to describe a sequence of points along the curve that would be the result of the command  \cs{psBsplineNodes}\{B\}\{5\}, naming those arrays {\tt P.X}, {\tt P.Y} (for position), {\tt PNormal.X}, {\tt PNormal.Y}, {\tt PDelta.X} and {\tt PDelta.Y}. Must be preceded by a \cs{psBsplineNodes} command. (Nothing is drawn.)
+\item[\cs{bspcurvepointsE\{B\}\{5\}\{P\}}] does the same as \cs{bspcurvepoints}, but omits the first and last segments. Must be preceded by a \cs{psBsplineNodes}{\tt[E]} command.(Nothing is drawn.)
 \item[\cs{bspNode\{P\}\{5\}\{1.3\}\{Q\}}] requires that you first run \cs{bspcurvepoints}{\tt[E]} to create PostScript arrays with basename {\tt P}. It then sets a node {\tt Q} at position $t=1.3$ on the curve. (Nothing is drawn.) 
 \item[\cs{bspFnNode\{P\}\{5\}\{2.3\}\{Q\}}] requires that you first run \cs{bspcurvepoints}{\tt[E]} to create PostScript arrays with basename {\tt P}. It then sets a node {\tt Q} at position $x=1.3$ on the curve. (Nothing is drawn.) The result is meaningful only for a B-spline curve that is the graph of a function of $x$ and where $x_0<x_1<\cdots$.
 \item[\cs{psBsplineInterp\{S\}\{4\}}] will construct a sequence {\tt SB0}..{\tt SB4} for which the associated B-spline curve interpolates {\tt S0}..{\tt S4}. (Nothing is drawn---you have to then issue the command \cs{psBsplineNodes\{SB\}\{4\}}.)
-\item[\cs{psBsplineInterpC\{S\}\{4\}}] will construct a sequence {\tt SB0}..{\tt SB5} for which the associated closed B-spline curve interpolates {\tt S0}..{\tt S4}. (Nothing is drawn---you have to then issue the command \cs{psBsplineNodesC\{SB\}\{5\}}.)
+\item[\cs{psBsplineInterpC\{S\}\{4\}}] will construct a sequence {\tt SB0}..{\tt SB5} for which the associated closed B-spline curve interpolates {\tt S0}..{\tt S4}. (Nothing is drawn --- you have then to issue the command \cs{psBsplineNodesC\{SB\}\{5\}}.)
 \item[\cs{thickBspline\{B\}\{5\}\{12pt\}\{<graphic to clip>\}}] defines a clipping path 12{\tt pt} wide around the B-spline curve with control points {\tt B0}..{\tt B5}, then draws the {\tt <graphic>} clipped to that path.
-\item[\cs{bspcurvenodes\{P\}\{Q\}}] creates a node sequence {\tt Q0} {\tt Q1},... from the position data in the arrays {\tt P.X}, {\tt P.Y}.
+\item[\cs{bspcurvenodes\{P\}\{Q\}}] creates a node sequence {\tt Q0} {\tt Q1},... from the position data in the arrays {\tt P.X}, {\tt P.Y} created a \cs{bspcurvepoints} macro.
 \end{description}
 Details and examples are provided below.
 
@@ -230,15 +229,16 @@ defines a sequence of \verb|\pnode|s with the node root {\tt P}: {\tt P0}=(2,1.5
 \end{verbatim}
 corresponding to the macros \verb|\psBspline|, \verb|\psBsplineC| and \verb|\psBsplineE|. The difference is that the macros with {\tt Nodes} in the name have as arguments  the root node name and the  last index, rather than the list of points. For example, with the above definition of {\tt P} in force, \verb|\psBsplineNodes{P}{2}| has exactly the same effect as  \verb|\psBspline(2,1.5)(3,4)(5,1).|
 \subsection{The \cs{bspcurvepoints} macros}
-There are two macros that provide for B-spline curves essentially the same functionality as the \verb|\pscurvepoints| macro from {\tt pstricks-add}. (That macro takes as input a parametric curve and constructs as output (at the PostScript level) arrays of data associated with the curve: the positions of points along the curve, the increment from the previous point and a normal vector to the curve. The principal uses for such data are (i) the \verb|\pspolylineticks| macro from {\tt pstricks-add}, which allows placement of ticks and other marks along a curve that has been approximated by a polyline; (ii) the \cs{polyIntersections} macro from \textsf{pst-node}, which allows you to find the points of intersection of the curve (approximated by  a polyline) and an arbitrary line.) The macros
+There are two macros that provide for B-spline curves essentially the same functionality as the \verb|\pscurvepoints| macro from {\tt pstricks-add}. (That macro takes as input a parametric curve and constructs as output (at the PostScript level) arrays of data associated with the curve: the positions of points along the curve, the increment from the previous point and a normal vector to the curve. The principal uses for such data are (i) the \verb|\pspolylineticks| macro from {\tt pstricks-add}, which allows placement of ticks and other marks along a curve that has been approximated by a polyline; (ii) the \cs{polyIntersections} macro from \textsf{pst-node}, which allows you to find the points of intersection of the curve (approximated by  a polyline) and an arbitrary line.) Following one of the \cs{psBsplineNodes} macros, the macros
 \begin{verbatim}
 \bspcurvepoints{<source name>}{<source max index>}{<dest. name>}
 \bspcurvepointsE{<source name>}{<source max index>}{<dest. name>}
 \end{verbatim}
-work, in the first case, for a relaxed, uniform B-spline curve, and in the second, for such a curve with its initial and final segments removed, corresponding to the output from \verb|\psBsplineE| rather than \verb|\psBspline|. In both cases, you may set the keyword {\tt plotpoints} (default value: $50$) to change the number of sample points on each  B\'ezier component. This will result in the construction of PostScript arrays with indices from $0$ to $n=$\textsf{num of segments}$\times$\textsf{(plotpoints-1)}. After running
+work, in the first case, for a relaxed, uniform B-spline curve, and in the second, for such a curve with its initial and final segments removed, corresponding to the output from \verb|\psBsplineE| rather than \verb|\psBspline|. In both cases, you may set the keyword {\tt plotpoints} (default value: $50$) to change the number of sample points on each  B\'ezier component. This will result in the construction of PostScript arrays with indices from $0$ to $n=$ \textsf{num of segments}$\times$\textsf{(plotpoints-1)}. After running
 \begin{verbatim}
 \pnodes{B}(1,2)(3,-1)(4,1)(6,2)% define B0..B3
-\bspcurvepoints[plotpoint=11]{B}{3}{P}
+\psBsplineNodes{B}{3}% draw B-spline with control pts B0..B3
+\bspcurvepoints[plotpoints=11]{B}{3}{P}% requires previous line
 \end{verbatim}
 the following PostScript arrays are created, each indexed from 0 to 30:
 \begin{verbatim}
@@ -246,15 +246,53 @@ P.X, P.Y (position)
 PNormal.X, PNormal.Y (normal vector)
 PDelta.X, PDelta.Y (increment from previous position)
 \end{verbatim}
-and these may be used in the usual way to create nodes. For example,
+and these may be used in the usual way to create nodes.  For example,
 \begin{verbatim}
-\pnode(! P.X 8 get P.Y 8 get){Q}
-\pnode(! PNormal.X 8 get PNormal.Y get){Dir}
-\psrline(Q)(1cm;{(Dir)})
+\pnode(! P.X 8 get P.Y 8 get ){Q}
+\pnode(! PNormal.X 8 get PNormal.Y 8 get ){Dir}
+\psrline{*-}(Q)(1cm;{(Dir)})
 \end{verbatim}
 places {\tt Q} at the position on the curve with index 8, defines {\tt Dir} to be a normal vector at that point, then draws a line from {\tt Q} of length {\tt 1cm} in the direction of that normal.
+\pspicture(-.5,-.5)(6.5,2.5)
+\pnodes{B}(1,2)(3,-1)(4,1)(6,2)% define B0..B3
+\psBsplineNodes{B}{3}% draw B-spline with control pts B0..B3
+\bspcurvepoints[plotpoints=11]{B}{3}{P}
+\pnode(! P.X 8 get P.Y 8 get ){Q}\psdot(Q)
+\pnode(! PNormal.X 8 get PNormal.Y 8 get ){Dir}
+\psrline{*-}(Q)(1cm;{(Dir)})
+\endpspicture
+
+In the next example, we use \cs{polyIntersections} from {\tt pst-plot} to locate intersections of a line and a B-spline curve.
+\begin{verbatim}
+\pspicture(-.5,-.5)(6.5,4.5)%
+\pnodes{B}(0,4)(1,-1)(3,4)(5,0)(6,3)% B0..B5
+\psBsplineNodes{B}{4}% draw B-spline with control pts B0..B4
+\pnode(1,2.8){A1}\pnode(2,2){A2}%
+\psdots[linecolor=red](A1)(A2)%
+\bspcurvepoints[plotpoints=30]{B}{4}{P}% construct PS arrays, 
+\bspcurvenodes{P}{Q}% turn them into nodes
+% indices 0..116 (=4*29)
+\polyIntersections{N1}{N2}(A1)(A2){Q}{116}%
+\psline{*-*}(N1)(N2)%
+% N1, N2 are points of intersection of curve with A1A2
+\Put{;75}(A1){A1}\Put{;75}(A2){A2}
+\endpspicture
+\end{verbatim}
+\pspicture(-.5,-.5)(6.5,4.5)%
+\pnodes{B}(0,4)(1,-1)(3,4)(5,0)(6,3)% B0..B5
+\psBsplineNodes{B}{4}% draw B-spline with control pts B0..B4
+\pnode(1,2.8){A1}\pnode(2,2){A2}%
+\psdots[linecolor=red](A1)(A2)%
+\bspcurvepoints[plotpoints=30]{B}{4}{P}% construct PS arrays, 
+\bspcurvenodes{P}{Q}% turn them into nodes
+% indices 0..116 (=4*29)
+\polyIntersections{N1}{N2}(A1)(A2){Q}{116}%
+\psline{*-*}(N1)(N2)% N1, N2 are points of intersection of curve with A1A2
+\Put{;75}(A1){A1}\Put{;75}(A2){A2}
+\endpspicture
+
 \subsection{Setting nodes on a B-spline curve}
-To set a node at parameter value $t$ on a B-spline curve after running \cs{bspcurvepoints}{\tt[E]}, call the macro
+To set a node at $t$ on a B-spline curve after\cs{bspcurvepoints}{\tt[E]}, call the macro
 \begin{verbatim}
 \bspNode{<control point root>}{<top index>}{<t>}{<node name>}
 \end{verbatim}
@@ -262,11 +300,36 @@ For example, if I have constructed a B-spline curve using control points $B_0$,$
 
 The macro \cs{bspcurvenodes\{P\}\{R\}} creates a node sequence {\tt R0}..{\tt Rn} at the locations specified by the arrays {\tt P.X}, {\tt P.Y}. (Those arrays must first have been created with one of the \cs{bspcurvepoints} macros.)
 \subsection{B-spline function curves}
-By this we mean an open B-spline curve which is the graph of a function $y=f(x)$ and whose orientation is toward the right. It is not analytically simple to specify a formula for $f$ in most cases, and to compute $y$ from $x$ involves (a) finding the index of the B\'ezier segment containing $x$; (b) solving the cubic $x(t)=x$ for $t$; (c)  substituting in $y(t)$. The package provides a macro to perform these calculations after generating the data using \cs{bspcurvepoints}{\tt[E]}:
+By this we mean an open B-spline curve which is the graph of a function $y=f(x)$ and whose orientation is toward the right. It is not analytically simple to specify a formula for $f$ in most cases, and to compute $y$ from $x$ involves (a) finding the index $k$ of the B\'ezier segment containing $x$; (b) solving the cubic $x_k(t)=x$ for $t$, $0\le t\le1$; (c)  substituting in $y_k(t)$. The package provides a macro to perform these calculations after generating the data using \cs{bspcurvepoints}{\tt[E]}:
 \begin{verbatim}
 \bspfnNode{<control point root>}{<top index>}{<x0>}{<node name>}
 \end{verbatim}
+\begin{verbatim}
+\pspicture(-.5,-.5)(6.5,4.5)%
+\pnodes{B}(0,4)(1,-1)(3,4)(5,0)(6,3)% B0..B4
+\psBsplineNodes{B}{4}% draw B-spline with control pts B0..B4
+% the curve is graph of a function of x
+\bspcurvepoints[plotpoints=10]{B}{4}{P}% construct PS arrays
+\bspFnNode{B}{4}{4.5}{QQ}% node QQ on curve at x=4.5
+\psdot[linecolor=red](QQ)%
+\psline[linestyle=dashed](QQ)(0,0 | QQ)
+\psline[linestyle=dashed](QQ)(QQ | 0,0)
+\psaxes(0,0)(-.5,-.5)(6,4)
+\endpspicture
+\end{verbatim}
+\pspicture(-.5,-.5)(6.5,4.5)%
+\pnodes{B}(0,4)(1,-1)(3,4)(5,0)(6,3)% B0..B4
+\psBsplineNodes{B}{4}% draw B-spline with control pts B0..B4
+% the curve is graph of a function of x
+\bspcurvepoints[plotpoints=10]{B}{4}{P}% construct PS arrays
+\bspFnNode{B}{4}{4.5}{QQ}% node QQ on curve at x=4.5
+\psdot[linecolor=red](QQ)%
+\psline[linestyle=dashed](QQ)(0,0 | QQ)
+\psline[linestyle=dashed](QQ)(QQ | 0,0)
+\psaxes(0,0)(-.5,-.5)(6,4)
+\endpspicture
 
+See also the penultimate example in the next section. 
 \section{B-spline Interpolation}
 This is the inverse problem. Being given points $(S_k)_{0\le k\le n}$, the goal is to produce the B-spline control points $B_k$ leading to the points $S_k$, so that the associated B-spline curve interpolates the $S_k$. 
 \subsection{Open curve}