| 1 |
|
| 2 |
\documentclass[10pt]{article} |
| 3 |
|
| 4 |
% Allows various tweaks to itemize as optional arguments. |
| 5 |
\usepackage{enumitem} |
| 6 |
|
| 7 |
% Gives the proof environment, with a box for QED. |
| 8 |
\usepackage{amsthm} |
| 9 |
|
| 10 |
% Needed for things like pmatrix. |
| 11 |
\usepackage{amsmath} |
| 12 |
|
| 13 |
% This allows footnotes from within array environment. |
| 14 |
\usepackage{footnote} |
| 15 |
\makesavenoteenv{array} |
| 16 |
|
| 17 |
% To adjust font sizes more easily. |
| 18 |
\usepackage{relsize} |
| 19 |
|
| 20 |
% This allows \verb in footnotes |
| 21 |
\usepackage{fancyvrb} |
| 22 |
|
| 23 |
% This allows me to say |
| 24 |
% \begin{figure}[H] |
| 25 |
% to mean ``here, and don't argue.'' Note the captial 'H'. |
| 26 |
\usepackage{float} |
| 27 |
|
| 28 |
% This is the modern thing to do, but the manual is 1300 pages! |
| 29 |
\usepackage{tikz} |
| 30 |
\usepackage{pgfplots} |
| 31 |
|
| 32 |
|
| 33 |
\begin{document} |
| 34 |
|
| 35 |
% Need this for fancyvrb to work. |
| 36 |
\VerbatimFootnotes |
| 37 |
|
| 38 |
% So that I don't have to type this all the time. |
| 39 |
\newcommand{\figput}{\textsc{FigPut}} |
| 40 |
|
| 41 |
|
| 42 |
\begin{center} |
| 43 |
{\Large \figput} |
| 44 |
|
| 45 |
Interactive Figures for \LaTeX |
| 46 |
|
| 47 |
\verb=https://github.com/rsfairman/figput= |
| 48 |
|
| 49 |
Randall Fairman |
| 50 |
|
| 51 |
Version 0.90, July 21, 2022 |
| 52 |
\end{center} |
| 53 |
|
| 54 |
\vskip 0.2cm |
| 55 |
|
| 56 |
The \textsc{FigPut} system allows \LaTeX\ to produce interactive |
| 57 |
figures. The system produces a static PDF file, as usual; in addition, |
| 58 |
the document can be viewed with an Internet browser and the figures |
| 59 |
become interactive. See the prototype in {\tt example/example.tex} |
| 60 |
to clarify what follows.\footnote{The version available on CTAN |
| 61 |
includes only what is strictly necessary to rebuild the document from |
| 62 |
scratch: {\tt example.tex} and {\tt exteernalcode.js}. The repository at {\tt |
| 63 |
github} includes all the files that result from the build process, |
| 64 |
and are necessary to view the PDF in either static or interactive |
| 65 |
form.} To view this example in its fully interactive form, see |
| 66 |
\verb=rsfairman.github.io/figput-example/=. |
| 67 |
|
| 68 |
% For some reason \textsc doesn't work within \section |
| 69 |
\section{Why \normalfont\scshape{FigPut}} |
| 70 |
|
| 71 |
There are many ways to produce figures in \LaTeX: MetaPost, TikZ, |
| 72 |
PSTricks, XY-pic, {\tt graphics}, {\tt picture}, and more. Creating |
| 73 |
technical figures is often an exercise in programming, and none of |
| 74 |
these is based on a commonly used programming |
| 75 |
language. \textsc{FigPut} is based on JavaScript (JS), which is |
| 76 |
probably the most widely used language today. Moreover, |
| 77 |
\figput\ allows figures to be animated and/or interactive. |
| 78 |
|
| 79 |
Aside from the fact that figures are specified with |
| 80 |
JavaScript, the system is normal \LaTeX. An important feature is that |
| 81 |
the two forms of the document -- static PDF and interactive -- look |
| 82 |
identical, with the same pagination and formatting. The reader can |
| 83 |
move between the printed version and the interactive version without |
| 84 |
needing to reorient. |
| 85 |
|
| 86 |
% For some reason \textsc doesn't work within \section |
| 87 |
\section{Using \normalfont\scshape{FigPut}} |
| 88 |
|
| 89 |
Here's a list of all the commands available in \figput: |
| 90 |
\begin{verbatim} |
| 91 |
\begin{figput} ... \end{figput} |
| 92 |
\FigPut |
| 93 |
\SetInnerMargin |
| 94 |
\SetOuterMargin |
| 95 |
\NeverSkip |
| 96 |
\AllowSkip |
| 97 |
\LoadFigureCode |
| 98 |
\end{verbatim} |
| 99 |
|
| 100 |
\subsection{The \LaTeX\ Side} |
| 101 |
|
| 102 |
Interactive figures are specified with the {\tt figput} |
| 103 |
environment or the \verb=\FigPut= command. The full form of the |
| 104 |
environment specification is |
| 105 |
\vskip 0.2cm |
| 106 |
|
| 107 |
\noindent\verb=\begin{figput}{<fig_name>,<fig_ht>}[=\emph{optional arguments}\verb=]= |
| 108 |
|
| 109 |
\noindent\verb= <JavaScript code>= |
| 110 |
|
| 111 |
\noindent\verb=\end{figput}= |
| 112 |
\vskip 0.2cm |
| 113 |
|
| 114 |
\noindent There are two mandatory arguments: \verb=<fig_name>= and |
| 115 |
\verb=<fig_ht>=. Every figure must have a unique name. This name is |
| 116 |
unrelated to any \verb=\label= or other identifier used for |
| 117 |
the figure. The \verb=<fig_ht>= is the height of the figure, expressed |
| 118 |
like other \LaTeX\ lengths in {\tt pt}, {\tt cm}, \emph{etc}. The |
| 119 |
figure is allocated this much vertical space on the page. The |
| 120 |
remaining optional arguments are discussed below. |
| 121 |
|
| 122 |
The {\tt <JavaScript code>} is used to draw the figure, and the only |
| 123 |
requirement is that it be given as |
| 124 |
\begin{verbatim} |
| 125 |
function <fig_name>(ctx) { |
| 126 |
... |
| 127 |
} |
| 128 |
\end{verbatim} |
| 129 |
The name of the JS function must match the figure name given to the |
| 130 |
{\tt figput} environment -- that's how the browser finds the correct |
| 131 |
JS function to draw a particular figure. The {\tt ctx} argument |
| 132 |
is required; it's the ``rendering context'' used for |
| 133 |
drawing.\footnote{\label{page-ctx} A variable of this type is commonly obtained in |
| 134 |
JavaScript by something like \vspace{-1.5mm} |
| 135 |
\begin{verbatim} |
| 136 |
let canvas = document.getElementById('where-drawing-happens'); |
| 137 |
let ctx = canvas.getContext('2d'); |
| 138 |
\end{verbatim} |
| 139 |
\vspace{-1.5mm} The full name for this type is {\tt |
| 140 |
CanvasRenderingContext2D}.} |
| 141 |
|
| 142 |
All of the JS functions for the various figures share the same |
| 143 |
name-space, and it is perfectly acceptable to share functions between |
| 144 |
figures or to define helper functions within a figure's |
| 145 |
environment. If many figures use the same {\tt drawDoodad()} |
| 146 |
function, then that function should appear with only a single figure, and |
| 147 |
it will be available to all of them. |
| 148 |
|
| 149 |
Use \verb=\SetInnerMargin= and \verb=\SetOuterMargin= to set the inner and outer |
| 150 |
margins (which may differ in a book that has left and right |
| 151 |
pages). The figure will be rendered within a rectangle that is set in |
| 152 |
from the left margin by the given amount. For example, you might say |
| 153 |
\begin{verbatim} |
| 154 |
\SetInnerMargin{150pt} |
| 155 |
\SetOuterMargin{150pt} |
| 156 |
\end{verbatim} |
| 157 |
so that the left edge of the figure is {\tt 150pt} from the left edge |
| 158 |
of the paper. These values can be changed before every figure, if that |
| 159 |
is appropriate. |
| 160 |
|
| 161 |
The coordinate system used within the JS code is based on big points ({\tt |
| 162 |
bp}), with the origin at the lower-left corner of the |
| 163 |
figure. The $y$-coordinate increases as you move \emph{up} the page. |
| 164 |
The $y$-axis is offset from the edge of the page by the |
| 165 |
value given to \verb=\SetInnerMargin= or \verb=\SetOuterMargin=. |
| 166 |
|
| 167 |
There is no need to begin the drawing by erasing the drawing |
| 168 |
area. That's done automatically. |
| 169 |
|
| 170 |
\subsubsection*{Optional Arguments} |
| 171 |
|
| 172 |
The arguments to {\tt figput} in {\tt []}, are optional. The first two |
| 173 |
of these arguments are \label{ht-above-below} |
| 174 |
\begin{verbatim} |
| 175 |
ht_above, ht_below |
| 176 |
\end{verbatim} |
| 177 |
If these arguments appear, then they must both appear, they must be |
| 178 |
the first two arguments, and they must be given in that order (above, |
| 179 |
then below); furthermore, they must include a unit specification, like {\tt |
| 180 |
bp}. An interactive figure may need a bit of extra clearance |
| 181 |
for an animation or space for widgets that aren't part of the |
| 182 |
figure itself. The static version of the document always uses |
| 183 |
\verb=<fig_ht>= for the figure height, while the interactive form adds |
| 184 |
this optional amount of space above and below the figure. If |
| 185 |
\verb=ht_below= is non-zero, then the $y$-axis is \verb=ht_below= |
| 186 |
above the bottom of the figure when drawn interactively. |
| 187 |
|
| 188 |
The remaining optional arguments may appear in any order and function |
| 189 |
as boolean flags: |
| 190 |
|
| 191 |
\begin{itemize}[itemsep=-1pt,leftmargin=2cm] |
| 192 |
\item[{\tt nostatic}] Use this when the figure is to be shown only |
| 193 |
when the document is viewed interactively. No figure will appear |
| 194 |
in the PDF. Almost certainly, the mandatory \verb=fig_ht= argument |
| 195 |
should be zero. The sum of \verb=ht_above= and \verb=ht_below= is |
| 196 |
used for the height of the interactive figure. |
| 197 |
\item[{\tt done}] indicates to the browser that the {\tt .tikz} |
| 198 |
should not be updated. |
| 199 |
\item[{\tt skip}] TikZ files can be large and take a long time to |
| 200 |
process. When this is set, the TikZ file won't be loaded and the |
| 201 |
figure will appear with a default ``not available'' message. |
| 202 |
\end{itemize} |
| 203 |
|
| 204 |
When the composition of a figure is complete, it often makes sense to |
| 205 |
turn on the {\tt done} and {\tt skip} flags. Using {\tt skip} saves |
| 206 |
time, and {\tt done} prevents inadvertent overwriting of a {\tt .tikz} |
| 207 |
file that you're happy with. However, to see the complete output, with |
| 208 |
your figures, you would have to go back and tediously remove all of |
| 209 |
the {\tt skip} flags. Use \verb=\NeverSkip= to avoid that tedium and |
| 210 |
disable all the {\tt skip} |
| 211 |
flags that occur until the next \verb=\AllowSkip=. |
| 212 |
|
| 213 |
\subsection*{The {\tt \textbackslash FigPut} Command} |
| 214 |
|
| 215 |
\verb=\FigPut= takes exactly the same arguments as the {\tt figput} |
| 216 |
environment, but the JS code must appear in an external file. The |
| 217 |
location of this external file is indicated with |
| 218 |
\verb=\LoadFigureCode=. If the code is found in {\tt mydrawcode.js}, |
| 219 |
then |
| 220 |
\begin{verbatim} |
| 221 |
\LoadFigureCode{mydrawcode.js} |
| 222 |
\end{verbatim} |
| 223 |
must appear somewhere in the {\tt .tex} file. |
| 224 |
|
| 225 |
It is often easier to use an external file to consolidate the drawing |
| 226 |
code in fewer files (or a single file). Not only |
| 227 |
does it make the {\tt .tex} file shorter and easier to navigate, but it |
| 228 |
allows the use of programming tools tailored to JS. For instance, |
| 229 |
the code could be written in TypeScript and compiled to JS. On the other |
| 230 |
hand, if the code for the figures is brief, then it may be clearer and more |
| 231 |
direct to use the {\tt figput} environment so that the code is in the |
| 232 |
{\tt .tex} file. |
| 233 |
|
| 234 |
\subsubsection*{Additional Remarks} |
| 235 |
|
| 236 |
There is no explicit provision in \textsc{FigPut} for changing the |
| 237 |
body of the text based on whether the document is to be viewed statically |
| 238 |
or interactively. This is intentional. The aim is for the text and its |
| 239 |
layout to be \emph{identical} in the two scenarios. However, it would |
| 240 |
be relatively straightforward to set up a couple of commands like |
| 241 |
\begin{verbatim} |
| 242 |
\newcommand{\statictext}[1]{#1} |
| 243 |
\newcommand{\intereactivetext}[1]{ } |
| 244 |
\end{verbatim} |
| 245 |
In the above example, anything that appears in \verb=\statictext{}= |
| 246 |
will pass through to the \LaTeX\ document, while everything in |
| 247 |
\verb=\interactivetext{}= will be ignored. Swap these two definitions |
| 248 |
depending on whether the document is being compiled for interactive or |
| 249 |
static reading. |
| 250 |
|
| 251 |
\subsection{Workflow} |
| 252 |
|
| 253 |
There are several phases to composing and releasing a document. The |
| 254 |
first phase is a loop through writing the \LaTeX, compiling it, viewing |
| 255 |
the output in a browser and generating TikZ, until the document is |
| 256 |
done. Everything in the first phase is local to your machine. The |
| 257 |
second phase is posting the result to a public-facing website. The |
| 258 |
first phase is discussed here; see Section \ref{sec-distributing} for |
| 259 |
the second phase. |
| 260 |
|
| 261 |
\subsubsection*{Setup} |
| 262 |
|
| 263 |
The functionality of \figput\ is given by {\tt figput.sty}. It |
| 264 |
requires the following packages: {\tt zref}, {\tt xsim}, {\tt tikz} |
| 265 |
and {\tt verbatim}. |
| 266 |
|
| 267 |
A typical arrangement is to have a {\tt javascript} |
| 268 |
directory with the files for the browser side of the framework, and a |
| 269 |
\LaTeX\ directory where the document is written in the usual way. The {\tt |
| 270 |
javascript} directory contains the JS files and the one HTML file needed |
| 271 |
to provide the browser front-end, and you'll also find {\tt server.py}. |
| 272 |
This Python script runs a local server so that your browser can |
| 273 |
open and view the document being written.\footnote{This requires |
| 274 |
Python 3 -- although that's probably obvious these days.} In principle, it's no |
| 275 |
different than a normal web-server, but it is tailored in several |
| 276 |
ways to the task at hand. To invoke this server, use the command-line |
| 277 |
to go to the {\tt javascript} directory and type |
| 278 |
\begin{verbatim} |
| 279 |
python server.py directory/nameof.pdf [port_num] |
| 280 |
\end{verbatim} |
| 281 |
The {\tt directory/nameof.pdf} argument is required and should be the |
| 282 |
path from the current ({\tt javascript}) directory to the PDF being |
| 283 |
generated by \LaTeX. Often, this will be something like |
| 284 |
\begin{verbatim} |
| 285 |
../../latex_area/num_theory/hairy_math.pdf |
| 286 |
\end{verbatim} |
| 287 |
The optional \verb=port_num= argument indicates the TCP/IP port on which the |
| 288 |
server will listen. It defaults to 8000. In principle, any integer in |
| 289 |
the range $[0,2^{16})$ could appear here, but certain values are |
| 290 |
restricted and others may already be in use. Stick to values |
| 291 |
in the range 8000-8100, and you should be safe.\footnote{See |
| 292 |
\verb=en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers=} |
| 293 |
|
| 294 |
By using different port numbers, it's possible to run several servers |
| 295 |
at once, so that multiple documents can be viewed and edited at the |
| 296 |
same time. Once the server is running, point your browser to |
| 297 |
\verb=localhost:8000= (or whatever \verb=port_num= you've chosen) to |
| 298 |
load the document. |
| 299 |
|
| 300 |
As stated, {\tt server.py} differs from a normal web-server in certain |
| 301 |
ways. This is done to make it easier to work with a document while it |
| 302 |
is being written. Once the document is complete, it can be served by a |
| 303 |
normal web-server. |
| 304 |
|
| 305 |
\subsubsection*{Additional Files} |
| 306 |
|
| 307 |
There are two additional directories in the {\tt javascript} directory: |
| 308 |
{\tt development} and {\tt release}. \figput\ was written in |
| 309 |
TypeScript, and the {\tt .ts} files are in {\tt development}. Even if |
| 310 |
you don't want to modify the system, the TypeScript files are easier |
| 311 |
to follow than the JavaScript files, and are the first place to look to |
| 312 |
clarify how the system works internally. There are four files: |
| 313 |
\begin{itemize}[itemsep=-1pt,leftmargin=1cm] |
| 314 |
\item{\tt main.ts} is the main entry-point for the program. This is |
| 315 |
unlikely to interest anyone who wants to simply use \figput. |
| 316 |
\item{\tt layout.ts} handles page layout -- also uninteresting to most people. |
| 317 |
\item{\tt widgets.ts} has the code for the various widgets. If widgets |
| 318 |
aren't acting the way you expect, then look here. |
| 319 |
\item{\tt tikz.ts} handles lower-level geometry, and conversion from |
| 320 |
JS to TikZ. Look here for details about the {\tt Point2D} and |
| 321 |
{\tt FPath} classes. |
| 322 |
\end{itemize} |
| 323 |
|
| 324 |
Two files found in the {\tt javascript} directory are {\tt |
| 325 |
pdf.worker.min.js} and {\tt pdf.js}. These are the source files for |
| 326 |
Mozilla's pdf.js library. The complete project can be found at |
| 327 |
\verb=github.com/mozilla/pdf.js=. The files are included here because, |
| 328 |
when developing a \LaTeX\ document on your local machine, it would be |
| 329 |
pointless (and slow) to download these files every time an updated |
| 330 |
version of your document is loaded. |
| 331 |
|
| 332 |
The {\tt release} directory contains the files to be used when the |
| 333 |
document is released to a public-facing website. As noted above, {\tt |
| 334 |
server.py} works differently than a normal web-server. The release |
| 335 |
process is discussed in more detail in Section \ref{sec-distributing}. |
| 336 |
|
| 337 |
\subsubsection*{From JavaScript to TikZ} |
| 338 |
|
| 339 |
Once the server is running, a browser can view documents created with |
| 340 |
\figput, but the figures will not be visible in |
| 341 |
the PDF document until a TikZ file is provided. The \emph{Get TikZ} |
| 342 |
button in the browser window generates the TikZ files. The server |
| 343 |
will save these files to the same directory as the PDF file. Note that |
| 344 |
a TikZ file will only be generated if the figure has been scrolled |
| 345 |
into view (or nearly into view) since the document was loaded. |
| 346 |
|
| 347 |
Because TikZ files can take time to load, it's often useful to |
| 348 |
compose the figures one (or a few) at a time. Apply the optional |
| 349 |
{\tt done} argument for any figures that are complete, and the |
| 350 |
\emph{Get TikZ} button will not generate TikZ files for them. You may |
| 351 |
want a particular frame from an animation; once you have the right |
| 352 |
frame, it would be frustrating to accidentally overwrite it in the course of |
| 353 |
working on some other figure. Using {\tt done} prevents that from happening. |
| 354 |
|
| 355 |
\subsection{JavaScript Drawing} |
| 356 |
|
| 357 |
In most respects, any JS code can be used with FigPut, but it must be |
| 358 |
possible to translate the JS drawing commands to TikZ, and that leads |
| 359 |
to certain requirements. In a nutshell, all drawing must be done using a |
| 360 |
class that is very similar to JS's built-in {\tt Path2D} class. |
| 361 |
|
| 362 |
If this is too restrictive, then it is possible to side-step the |
| 363 |
requirement with a bit of extra effort. If you use JS drawing commands |
| 364 |
that are off-limits, like {\tt drawImage()}, then the interactive version |
| 365 |
will work fine, but you'll have to find some other way to generate the |
| 366 |
figure for inclusion in the static PDF. Any of the usual methods of |
| 367 |
generating figures for \LaTeX\ documents will work, but now the two |
| 368 |
versions, interactive and static, are generated from different |
| 369 |
source-code. |
| 370 |
|
| 371 |
Earlier, in a footnote on p. \pageref{page-ctx}, it was a stated that |
| 372 |
the {\tt ctx} argument to your drawing function has the standard JS type, {\tt |
| 373 |
CanvasRenderingContext2D}. That's not always true. Any drawing |
| 374 |
done \emph{to the browser} is \emph{precisely} an object of this |
| 375 |
type. If you only care about seeing your document within the browser |
| 376 |
framework, and you don't care about generating figures for a |
| 377 |
standalone {\tt .pdf} file, then that's all you need to know. Draw |
| 378 |
with JS however you like. |
| 379 |
|
| 380 |
To produce TikZ output, the built-in {\tt CanvasRenderingContext2D} |
| 381 |
must be ``spoofed.'' All of the drawing commands that normally go to |
| 382 |
the built-in JS browser code go to \figput's {\tt CTX} class |
| 383 |
instead, where they are converted to TikZ output. |
| 384 |
This class implements a sub-set of the full list of drawing |
| 385 |
commands normally available. The permitted commands are |
| 386 |
\begin{verbatim} |
| 387 |
ctx.fill() |
| 388 |
ctx.stroke() |
| 389 |
ctx.lineWidth |
| 390 |
\end{verbatim} |
| 391 |
These work almost as they normally do. The {\tt lineWidth} is the |
| 392 |
thickness of any paths, and can be thought of as being in \TeX's {\tt |
| 393 |
bp} units. The {\tt fill()} and {\tt stroke()} commands normally |
| 394 |
take a JS {\tt Path2D} object, but you should pass an object of type |
| 395 |
{\tt FPath} instead. |
| 396 |
|
| 397 |
The methods of {\tt FPath} listed below are exactly like those found |
| 398 |
in {\tt Path2D}. They add a new segment to an existing {\tt FPath}, |
| 399 |
obtained with {\tt new}. See any JS resource for an explanation. |
| 400 |
\begin{itemize}[itemsep=-1pt,leftmargin=*] |
| 401 |
\item {\tt closePath()} |
| 402 |
\item {\tt moveTo()} |
| 403 |
\item {\tt lineTo()} |
| 404 |
\item {\tt bezierCurveTo()} |
| 405 |
\item {\tt ellipse()} |
| 406 |
\end{itemize} |
| 407 |
And these methods of {\tt FPath} are new -- they have no counterpart |
| 408 |
in {\tt Path2D}. |
| 409 |
\begin{itemize}[itemsep=-1pt,leftmargin=*] |
| 410 |
\item {\tt addPath(p)} appends the {\tt FPath}, {\tt p}, to an |
| 411 |
existing {\tt FPath}. |
| 412 |
\item {\tt translate(p)} translates an {\tt FPath} by the given {\tt Point2D}. |
| 413 |
\item {\tt rotate(angle)} rotates an {\tt FPath} by the given angle, |
| 414 |
in radians. |
| 415 |
\item {\tt scale(s)} scales an {\tt FPath} by the given factor |
| 416 |
(relative to the origin). |
| 417 |
\item {\tt reflectX()} reflects an {\tt FPath} across the $x$-axis. |
| 418 |
\item {\tt reflectXY()} reflects an {\tt FPath} across the $x$ and $y$-axis. |
| 419 |
\item {\tt rotateAbout(angle,p)} rotates a given {\tt FPath} about the |
| 420 |
given {\tt Point2D} by the given angle. |
| 421 |
|
| 422 |
The methods above apply to an existing {\tt FPath} and return a new {\tt FPath}. |
| 423 |
\item {\tt parametricToBezier(f,t0,t1,n)} converts a parametric |
| 424 |
function, {\tt f(t)}, to a path consisting of {\tt n} B\'ezier |
| 425 |
curves as {\tt t} runs from {\tt t0} to {\tt t1}. The function |
| 426 |
must be defined to return {\tt Point2D} objects. |
| 427 |
|
| 428 |
This is a static method, so it returns a new {\tt FPath} that is unrelated to any existing {\tt FPath} objects. |
| 429 |
\end{itemize} |
| 430 |
There are several additional methods in {\tt FPath} that may be |
| 431 |
useful, but they haven't yet been tested well enough to mention |
| 432 |
here (and they may change in the future). See the source code if |
| 433 |
you're adventurous. |
| 434 |
|
| 435 |
Several of the methods above mention the {\tt Point2D} class, and it's what you would expect. Use |
| 436 |
\begin{verbatim} |
| 437 |
new Point2D(x,y); |
| 438 |
\end{verbatim} |
| 439 |
to create these objects. There's a long list of methods defined in the |
| 440 |
class: {\tt translate()}, {\tt rotate()}, {\tt length()}, |
| 441 |
\emph{etc}. See the source code for a complete list. |
| 442 |
|
| 443 |
Text is drawn in a way that is further from how it's normally done in |
| 444 |
JS. Instead of calling {\tt ctx.fillText()}, there are three top-level |
| 445 |
functions (not part of any class) for drawing text: |
| 446 |
\begin{verbatim} |
| 447 |
drawText(ctx,txt,x,y,dx,dy); |
| 448 |
drawTextBrowserOnly(ctx,txt,x,y,dx,dy); |
| 449 |
drawTextTikZOnly(ctx,txt,x,y,dx,dy); |
| 450 |
\end{verbatim} |
| 451 |
The arguments are the same in the three cases, but the first function will draw |
| 452 |
text to both the browser window and the TikZ, while the other two will |
| 453 |
draw the text to only one destination or the other. The {\tt ctx} is |
| 454 |
the same as the argument to your drawing function, {\tt txt} is the |
| 455 |
string to be drawn, {\tt x,y} is the location of the text \emph{for |
| 456 |
the browser}, relative to the lower-left corner of the |
| 457 |
bounding-box. When the text is drawn to TikZ, it is drawn at {\tt |
| 458 |
x+dx,y+dy}. Because the fonts used in the browser and in TikZ differ |
| 459 |
slightly, sometimes it's necessary to tweak the TikZ placement. Setting |
| 460 |
\begin{verbatim} |
| 461 |
ctx.font = '10px san-serif'; |
| 462 |
\end{verbatim} |
| 463 |
sets the browser font to something very close the default font used |
| 464 |
by TikZ, but it's not a perfect match. The {\tt dx} and {\tt dy} |
| 465 |
arguments are optional and default to {\tt 0}. |
| 466 |
|
| 467 |
As a bonus, the static method, {\tt Numerical.newton()}, can be used to |
| 468 |
solve $f(x) = y$ for $x$, given $y$. It's a naive implementation of Newton-Raphson. |
| 469 |
|
| 470 |
\subsection{JavaScript Widgets} |
| 471 |
|
| 472 |
The foregoing framework could be used an an alternative to TikZ, |
| 473 |
PSTricks, MetaPost, \emph{etc.}, if your aim is strictly static |
| 474 |
output. To make the figures interactive, there must be some means to |
| 475 |
accept user input -- widgets. |
| 476 |
|
| 477 |
All widgets have a static {\tt register()} method. Do not use {\tt |
| 478 |
new} to create widgets! Registering a widget has the effect of |
| 479 |
making it available for user input, and drawing it too (with one |
| 480 |
exception). The arguments to these {\tt register()} methods vary with |
| 481 |
the widget, but the first argument is always the {\tt ctx} known to |
| 482 |
the drawing function, and the last argument is always a {\tt name} (a |
| 483 |
string). One drawing could have several widgets of the same kind and |
| 484 |
{\tt name} is used to distinguish |
| 485 |
them. So, if a particular drawing has three buttons, then they could |
| 486 |
be created/registered with |
| 487 |
\begin{verbatim} |
| 488 |
let b1 = ButtonWidget.register(ctx,...,"first"); |
| 489 |
let b2 = ButtonWidget.register(ctx,...,"second"); |
| 490 |
let b3 = ButtonWidget.register(ctx,...,"third"); |
| 491 |
\end{verbatim} |
| 492 |
These names only need to be unique within a single drawing and one |
| 493 |
type of widget. So, in the example above, two {\tt |
| 494 |
DraggableDotWidget}s could be registered in the same drawing as |
| 495 |
the {\tt ButtonWidget}s with |
| 496 |
\begin{verbatim} |
| 497 |
let dd1 = DraggableDotWidget.register(ctx,...,"first"); |
| 498 |
let dd2 = DraggableDotWidget.register(ctx,...,"second"); |
| 499 |
\end{verbatim} |
| 500 |
|
| 501 |
\subsubsection{\tt ButtonWidget} |
| 502 |
|
| 503 |
These are registered with |
| 504 |
\begin{verbatim} |
| 505 |
ButtonWidget.register(ctx,x,y,text,name); |
| 506 |
\end{verbatim} |
| 507 |
The {\tt x,y} argument is the location of the button, relative to the |
| 508 |
lower-left corner. The {\tt text} is what is shown as the message |
| 509 |
within the button. Buttons work by calling back to your drawing code |
| 510 |
whenever they are clicked. Every time the button is clicked, the |
| 511 |
entire drawing function is executed. |
| 512 |
|
| 513 |
There are two useful fields of {\tt ButtonWidget}. If {\tt b} is a |
| 514 |
{\tt ButtonWidget}, then {\tt b.clickState} toggles between {\tt true} and {\tt |
| 515 |
false} with every click of the button, while {\tt b.resetState} is |
| 516 |
set to {\tt true} whenever the button is clicked -- and remains {\tt |
| 517 |
true} until your drawing code resets it. |
| 518 |
|
| 519 |
\subsubsection{\tt NumberInputWidget} |
| 520 |
|
| 521 |
This is similar to {\tt ButtonWidget}, and is used to input single |
| 522 |
numbers. It's registered with |
| 523 |
\begin{verbatim} |
| 524 |
NumberInputWidget.register(ctx,x,y,v,name); |
| 525 |
\end{verbatim} |
| 526 |
The {\tt v} argument is the initial numerical value shown in the |
| 527 |
widget. Whenever the user changes this value, the widget calls back |
| 528 |
and executes the entire drawing function. To obtain this value, call |
| 529 |
{\tt getValue()} on the relevant widget. Because this widget relies |
| 530 |
on HTML, {\tt getValue()} returns a string. It may be necessary to |
| 531 |
call the JS {\tt parseFloat()} or {\tt parseInt()} functions on this |
| 532 |
value. |
| 533 |
|
| 534 |
\subsubsection{\tt DraggableDotWidget} |
| 535 |
|
| 536 |
A ``draggable dot'' is a small dot that can be grabbed by the mouse |
| 537 |
and moved around. They're registered with |
| 538 |
\begin{verbatim} |
| 539 |
DraggableDotWidget.register(ctx,x,y,name); |
| 540 |
\end{verbatim} |
| 541 |
To determine where the user has moved a dot, refer to the widget's |
| 542 |
{\tt widgetX} and {\tt widgetY} fields. |
| 543 |
|
| 544 |
Most widgets are used ``off to the side'' and wouldn't normally |
| 545 |
interfere with the way the figure is drawn, but these dots are typically |
| 546 |
used as part of the drawing itself. The order in which dots are drawn |
| 547 |
may matter. Sometimes a dot should be drawn first, so that other |
| 548 |
elements of the figure may be drawn over it; and sometimes a dot |
| 549 |
should be drawn last so that nothing can obscure it. For this |
| 550 |
reason, unlike other widgets, registering the widget does not also |
| 551 |
draw the widget. An explicit call to the widget's {\tt |
| 552 |
draw(ctx)} method must be made to draw the dot. |
| 553 |
|
| 554 |
\subsubsection{\tt DraggableDrawWidget} |
| 555 |
|
| 556 |
This is similar to {\tt DraggableDotWidget}, but it has no default |
| 557 |
drawing behavior. The user must provide functions to specify what is |
| 558 |
to be drawn. So it can also be a draggable polygon, or a draggable |
| 559 |
anything-you-can-draw. Register these with |
| 560 |
\begin{verbatim} |
| 561 |
DraggableDrawWidget.register(ctx,x,y, |
| 562 |
drawFcn,drawSelFcn,testPosFcn, |
| 563 |
name); |
| 564 |
\end{verbatim} |
| 565 |
The {\tt drawFcn} must be defined to take the {\tt ctx} as the sole |
| 566 |
argument. It can draw whatever it wants, noting that the origin is |
| 567 |
shifted so that drawing should typically take place relative to {\tt |
| 568 |
(0,0)}, not {\tt (widgetX,widgetY)}. In most cases, this means |
| 569 |
that the drawing code is independent of where the item is on the |
| 570 |
page. {\tt drawFcn} must return an {\tt FPath} object to indicate |
| 571 |
the ``clickable area'' for the item. For example, if what is being |
| 572 |
drawn is a small square, then the function might be defined as |
| 573 |
\begin{verbatim} |
| 574 |
function drawSquare(ctx) { |
| 575 |
let p = new FPath(); |
| 576 |
// p.lineTo, moveTo, etc., to make a square. |
| 577 |
ctx.fillPath(p); |
| 578 |
return p; |
| 579 |
} |
| 580 |
\end{verbatim} |
| 581 |
The value returned is noted, and any click in the interior of the path |
| 582 |
-- as determined by the JS function {\tt isPointInPath()} -- |
| 583 |
is taken to be a valid click on the object, to select it and drag it around. |
| 584 |
|
| 585 |
The {\tt drawSelFcn} argument to {\tt register} is identical to the |
| 586 |
{\tt drawFcn} argument, but it is called to draw the item when it is |
| 587 |
``selected.'' Often, the only difference between the two functions |
| 588 |
will be the color used to draw the item. |
| 589 |
|
| 590 |
The {\tt testPosFcn} argument is used to determine whether a |
| 591 |
particular location for the item is acceptable. For example, an item |
| 592 |
could be limited to a particular region. This is called every time the |
| 593 |
mouse is moved, after the item has been selected, up until the mouse |
| 594 |
button is released. The function takes five arguments and returns a |
| 595 |
boolean. The five arguments are the proposed {\tt x,y} position (the |
| 596 |
mouse location), followed by the width of the drawing area, then the |
| 597 |
height above and below the $x$-axis, where the width is equal to the |
| 598 |
text width. Return {\tt true} if the |
| 599 |
proposed {\tt x,y} is acceptable; {\tt false} otherwise. At a minimum, |
| 600 |
the function should typically check that {\tt x,y} is inside the |
| 601 |
figure rectangle. |
| 602 |
|
| 603 |
\subsubsection{\tt LoopAnimWidget} |
| 604 |
|
| 605 |
This widget and the next one ({\tt OpenAnimWidget}) are for |
| 606 |
animations, and work similarly. A {\tt LoopAnimWidget} is used for |
| 607 |
animations that run in a repeating loop. There are many arguments to |
| 608 |
register them. |
| 609 |
\begin{verbatim} |
| 610 |
LoopAnimWidget.register(ctx,x,y,scale,visWidget, |
| 611 |
steps,start,timeStep, |
| 612 |
visSteps,visFastSlow,visPauseRun,visCircle,triGrab, |
| 613 |
name); |
| 614 |
\end{verbatim} |
| 615 |
The {\tt x,y} values are the location of the center of the circle that |
| 616 |
is the primary element of the widget. The widget can be made larger or |
| 617 |
smaller by changing the {\tt scale} -- a value of {\tt 1.0} makes the |
| 618 |
circle 40~{\tt bp} in radius. The {\tt visWidget} argument is a |
| 619 |
boolean; set it to {\tt false} to run an animation without |
| 620 |
showing the user this widget. |
| 621 |
|
| 622 |
{\tt steps} is the integral number of steps that make up one loop of |
| 623 |
the animation. {\tt start} is the step on which the animation |
| 624 |
starts -- so that the animation starts with the {\tt start}-th |
| 625 |
frame. {\tt timeStep} is the number of milliseconds between |
| 626 |
frames. Unless the machine is \emph{very} fast, anything less than |
| 627 |
{\tt 10} for {\tt timeStep} is probably pointless, and a setting of |
| 628 |
{\tt 50} or {\tt 75} is more reasonable considering the human eye. |
| 629 |
|
| 630 |
The next group of arguments -- {\tt visSteps} through {\tt triGrab} -- are |
| 631 |
all booleans. They determine whether certain parts of the widget are |
| 632 |
visible. {\tt visSteps} shows or hides an area above the circle that |
| 633 |
can be used to change the number of steps taken per frame. The user |
| 634 |
can use this control to skip frames of the animation. {\tt |
| 635 |
visFastSlow} is for some ``sideways chevrons,'' in an area below the circle, |
| 636 |
that allow the user to change the number of milliseconds per |
| 637 |
frame. {\tt vsPauseRun} is for a pause/run control below the |
| 638 |
circle. {\tt visCircle} is for the entire circle. The circle has a |
| 639 |
small grabable triangle to indicate which frame is being shown; use |
| 640 |
{\tt triGrab} to show or hide the triangle. |
| 641 |
|
| 642 |
To draw a particular frame from your drawing function, refer to the |
| 643 |
{\tt curStep} field of the object. This will be a value in the range |
| 644 |
from 0 to the {\tt steps} argument to {\tt register()}. |
| 645 |
|
| 646 |
\subsubsection{\tt OpenAnimWidget} |
| 647 |
|
| 648 |
This widget is for open-ended animations that don't run in a loop, |
| 649 |
but continue ``forever.'' Whereas {\tt LoopAnimWidget} indicates the |
| 650 |
frame being viewed relative to a circle, {\tt OpenAnimWidget} uses a |
| 651 |
bar, something like a scroll-bar. Registration is similar to |
| 652 |
{\tt LoopAnimWidget}: |
| 653 |
\begin{verbatim} |
| 654 |
OpenAnimWidget.register(ctx,x,y,scale,width,visWidget, |
| 655 |
timeStep,decay, |
| 656 |
visSteps,visFastSlow,visPauseRun,visBar,barGrab, |
| 657 |
name); |
| 658 |
\end{verbatim} |
| 659 |
The {\tt ctx}, {\tt x}, {\tt y}, {\tt scale} and {\tt visWidget} |
| 660 |
arguments are as for {\tt LoopAnimWidget}. {\tt width} sets the width |
| 661 |
of the bar, in {\tt bp}. |
| 662 |
|
| 663 |
{\tt timeStep} is in milliseconds, as for {\tt LoopAnimWidget}. The |
| 664 |
{\tt decay} is used to adjust the rate of travel of the ``thumb'' along the |
| 665 |
bar as the animation progresses. Since the animation is potentially |
| 666 |
infinite, the thumb moves quickly early in the animation, then moves |
| 667 |
more and more slowly, so that it never quite reaches the end of the |
| 668 |
bar. The position of the thumb is given by |
| 669 |
$$1 - {1\over (1+{\tt decay})^s},$$ |
| 670 |
expressed as a fraction of the bar's total length, where $s$ is the |
| 671 |
frame count (\emph{i.e.}, {\tt curStep}). A reasonable setting for {\tt |
| 672 |
decay} is something in the range of $10^3$ to $10^6$, although it |
| 673 |
will depend on the animation. |
| 674 |
|
| 675 |
The arguments from {\tt visSteps} to {\tt barGrab} are all boolean and |
| 676 |
control which controls that make up the widget are visible. They're |
| 677 |
like their counterparts in {\tt LoopAnimWidget}, except that {\tt |
| 678 |
OpenAnimWidget} uses a bar instead of a circle. |
| 679 |
|
| 680 |
\section{Distributing a Complete Document} |
| 681 |
\label{sec-distributing} |
| 682 |
|
| 683 |
The PDF document is no different than any other PDF, and can be |
| 684 |
distributed in the usual ways. When moving the document in interactive |
| 685 |
form to a public-facing website, a few steps are necessary. |
| 686 |
|
| 687 |
See the {\tt javascript/release} directory. It has two files: {\tt |
| 688 |
figput.html} and {\tt figput.js}. The {\tt .js} file is just the |
| 689 |
four files used for the local version ({\tt main.js}, \emph{etc}.), |
| 690 |
consolidated to a single file and minified. These two files must |
| 691 |
appear on the web-server in the same directory as the various files |
| 692 |
that make up your document. |
| 693 |
|
| 694 |
{\tt figput.html} is only a few lines long, and there are two |
| 695 |
important changes that must be made. See the line that reads |
| 696 |
\vskip 0.2cm |
| 697 |
\noindent\verb!<body onload="doOpenDocument('unknown1',unknowny)" id="mainbody">! |
| 698 |
\vskip 0.2cm |
| 699 |
\noindent Change {\tt unknown1} to your document's name, \emph{without} the |
| 700 |
{\tt .pdf} suffix. If the document was generated from {\tt |
| 701 |
example.tex}, then {\tt unknown1} should be changed to {\tt example}. |
| 702 |
Second, change {\tt unknowny} to {\tt 0}. When the document is |
| 703 |
opened, this is the vertical position, in {\tt bp}, at which the document is |
| 704 |
opened. Setting {\tt unknonwy} to {\tt 0} means that the document |
| 705 |
will open at the top of the first page. Of course, it's possible |
| 706 |
that you want the document to open at some other location, in which |
| 707 |
case use some other value for {\tt unknowny}. |
| 708 |
|
| 709 |
The server needs {\tt figput.html} (after the modifications |
| 710 |
above), {\tt figput.js}, and the files that make up your |
| 711 |
document. These files consist of the {\tt .pdf} file, the {\tt .fig.aux} |
| 712 |
file, any {\tt .js} files referred to by \verb=\LoadFigureCode=, plus |
| 713 |
any {\tt .fjs} files generated by your document. The server does not |
| 714 |
need the {\tt .tikz} files. |
| 715 |
|
| 716 |
\section{Code Internals} |
| 717 |
|
| 718 |
An understanding of this section isn't necessary to use \figput; it's |
| 719 |
here to provide a bit of background for anyone who wants to improve |
| 720 |
or modify the framework. Most of \figput\ is in TypeScript, which |
| 721 |
should make it easier to follow. |
| 722 |
|
| 723 |
Throughout the various files that make up the system are |
| 724 |
{\tt BUG} annotations. These are not bugs \emph{per se}, but are more |
| 725 |
like infelicities, opportunities for improvement, or to draw attention |
| 726 |
to something confusing or problematic. If you want to contribute to |
| 727 |
\figput, then these are a good place to start. |
| 728 |
|
| 729 |
\subsection{\tt figput.sty} |
| 730 |
|
| 731 |
The {\tt .sty} file is well-commented and should be |
| 732 |
self-explanatory. However, I am far from an expert in \LaTeX3 |
| 733 |
programming. Here is a high-level list of ways in which it might be |
| 734 |
possible to improve things. |
| 735 |
|
| 736 |
\begin{itemize}[itemsep=-1pt,leftmargin=*] |
| 737 |
\item {\tt figput.sty} is written for \LaTeX3. The entire thing might |
| 738 |
be simpler if it were in Lua\TeX. |
| 739 |
\item The ability to explicitly specify the inner and outer margins |
| 740 |
used by \figput\ (with \verb=\SetInnerMargin= and |
| 741 |
\verb=SetOuterMargin=) is useful, but it would often suffice to |
| 742 |
default to the margins used by \LaTeX. How can those values be |
| 743 |
obtained? |
| 744 |
\item Someone who is more expert in \LaTeX3 could improve the code's |
| 745 |
clarity and brevity. |
| 746 |
\item It would be nice if \figput\ could create figures within a {\tt |
| 747 |
minipage}, but that would require extensive changes to both the |
| 748 |
\LaTeX\ and browser code. |
| 749 |
\end{itemize} |
| 750 |
|
| 751 |
\subsubsection*{A Quirk} |
| 752 |
|
| 753 |
\LaTeX\ on Windows has a quirk. \TeX\ will not write to a |
| 754 |
file whose type is executable. Thus, it won't write to |
| 755 |
a {\tt .pl} file (Perl), {\tt .py} (Python) file, \emph{etc.}, |
| 756 |
depending on how the machine is set up. \figput\ creates |
| 757 |
JavaScript files, which are typically saved as {\tt .js} files, and |
| 758 |
these may be seen as executable by Windows. Fortunately, |
| 759 |
browsers doesn't care what the suffix is, so \figput\ uses |
| 760 |
{\tt .jfs} as the suffix. |
| 761 |
|
| 762 |
This limitation on the file name suffix applies to \verb=\write=, but |
| 763 |
not to \verb=\write18=. \TeX\ is limited in this way to prevent |
| 764 |
accidental errors and for security. One solution might be to have the |
| 765 |
package write files using an acceptable suffix, then change the |
| 766 |
suffix with \verb=\write18=, which does not have this |
| 767 |
limitation. However, to use \verb=\write18= this way, \LaTeX\ would |
| 768 |
have to be invoked with something like |
| 769 |
\begin{verbatim} |
| 770 |
pdflatex -shell-escape |
| 771 |
\end{verbatim} |
| 772 |
which would be annoying. |
| 773 |
|
| 774 |
\subsection{\tt server.py} |
| 775 |
|
| 776 |
The server is a simple thing, so there's not much to say. It |
| 777 |
would be nice if it were written in a compiled language so |
| 778 |
that the user doesn't need to install Python. |
| 779 |
|
| 780 |
\subsection{Browser Code} |
| 781 |
|
| 782 |
This part is written in TypeScript (TS), which is essentially JS with |
| 783 |
type annotations. It must be translated |
| 784 |
to JS for the browser to run it, but TS code is easier to follow, and |
| 785 |
the type information heads off many programming errors. |
| 786 |
|
| 787 |
Although the program is (to my knowledge!) bug-free in the usual |
| 788 |
sense, there are plenty of {\tt BUG} annotations to draw attention to |
| 789 |
places where the code could be improved. Some of the higher-level |
| 790 |
possibilities for improvement are noted below. |
| 791 |
\begin{itemize}[itemsep=-1pt,leftmargin=*] |
| 792 |
\item \figput\ relies on the {\tt pdf.js} library for rendering |
| 793 |
PDFs. The result is not as crisp as I would like. It's unclear |
| 794 |
whether the problem is with the library itself, or how it is being |
| 795 |
used. Someone who knows that library well may be able to improve the |
| 796 |
output. Maybe a different library would work better. |
| 797 |
\item Most of the widgets do not rely on the DOM, but {\tt |
| 798 |
NumberInputWidget} and {\tt ButtonWidget} are based on the built-in |
| 799 |
DOM elements. It would be nice if these didn't use the DOM. |
| 800 |
\item Many additional widgets could be created. |
| 801 |
\item Adjust the font used for figures in the browser to make it more |
| 802 |
nearly identical to what appears in the PDF. |
| 803 |
\item Color is entirely neglected on the \LaTeX\ end of \figput. Browser output |
| 804 |
can be colored arbitrarily (with {\tt ctx.fillStyle} or {\tt |
| 805 |
ctx.strokeStyle}, as usual), but the TikZ output is limited to |
| 806 |
black and white. |
| 807 |
\item Double-buffer everything. Animations seem to run fine, |
| 808 |
without any noticeable flicker, but double-buffering \emph{all} |
| 809 |
drawing would put an end to any concerns about flicker. |
| 810 |
\item Animations should be turned off and stop generating events when |
| 811 |
they are scrolled out of view. This would save CPU cycles, which may |
| 812 |
matter for documents with many animations. |
| 813 |
\end{itemize} |
| 814 |
|
| 815 |
\noindent And some items that are more ambitious... |
| 816 |
\begin{itemize}[itemsep=-1pt,leftmargin=*] |
| 817 |
\item Allow figures to be set within a {\tt minipage} (mentioned above). |
| 818 |
\item Double-clicking a figure (or something) could enlarge the figure |
| 819 |
to give more room for interaction. |
| 820 |
\item Come up with a scheme so that the code that draws a figure could |
| 821 |
be made part of the document. For certain topics, the code that |
| 822 |
draws a figure can be as instructive as the figure itself. |
| 823 |
\item Extend the framework somehow so that it can be used within an |
| 824 |
IDE. Code that's mathematically-oriented is difficult to |
| 825 |
document within source code using simple text. It would be easier to |
| 826 |
understand if it's explained as \LaTeX\ output that appears |
| 827 |
in the source code, rather than in a separate document. |
| 828 |
\item Extend the framework to allow inclusion of snippets of |
| 829 |
\LaTeX\ output in standard HTML documents. Things like KaTeX and |
| 830 |
MathJax are convenient, but incomplete relative to \LaTeX. |
| 831 |
\end{itemize} |
| 832 |
|
| 833 |
\newpage |
| 834 |
|
| 835 |
\subsection*{Version History} |
| 836 |
|
| 837 |
\begin{itemize}[itemsep = -3pt] |
| 838 |
\item{0.90} -- July 21, 2022. I've been using this, privately, for |
| 839 |
several months. Numerous improvements and extensions are possible, |
| 840 |
but it definitely works. |
| 841 |
\end{itemize} |
| 842 |
|
| 843 |
|
| 844 |
\vskip 0.3cm |
| 845 |
\hrule |
| 846 |
\vskip 0.3cm |
| 847 |
|
| 848 |
|
| 849 |
Thanks to Dan Pratt for insights regarding TypeScript, and |
| 850 |
improvements to the code. |
| 851 |
|
| 852 |
Several people on {\tt tex.stackexchange} very |
| 853 |
patiently answered numerous questions. Thank you. |
| 854 |
|
| 855 |
|
| 856 |
|
| 857 |
\end{document} |