Debian Codegraph @

texmf-dist/source/latex/media9/media9.tex

raw
1 % Copyright 2012--\today Alexander Grahn
2 %
3 % This material is subject to the LaTeX Project Public License. See
4 % http://mirrors.ctan.org/macros/latex/base/lppl.txt
5 % for the details of that license.
6 %
7 \listfiles
8 %%%%%%%% pdfmanagement-testphase %%%%%%
9 \DocumentMetadata % activates the PDF management interface
10 {
11 %uncompress,
12 }
13 %%%%%%% /pdfmanagement-testphase %%%%%%
14 \documentclass[a4paper]{article}
15 \frenchspacing
16 %\usepackage[utf8]{inputenc}
17 \usepackage{textcomp}
18 \usepackage[attachfiles]{media9}
19 %\usepackage[draft]{media9}
20 \usepackage{animate}
21 \usepackage{fancyvrb}
22 \usepackage{float}
23 \usepackage{amssymb}
24 \usepackage[main=UKenglish,nil]{babel}
25 \usepackage{graphicx}
26 \usepackage{color}
27 %\usepackage[T1]{fontenc}
28 %%\usepackage{lmodern}
29 %\usepackage[scaled=0.85]{luximono}
30 \usepackage[tt=false]{libertine} %override beramono (doesn't look like tt font)
31 \usepackage[libertine]{newtxmath}
32 % \usepackage[scaled=0.83]{luximono} %override beramono (doesn't look like tt font)
33 \usepackage{microtype}
34 %\usepackage{float}
35 \usepackage{parskip}
36 \usepackage{tabls}
37 \usepackage{menukeys}
38 \usepackage{hyperref}
39 \usepackage{hypcap}
40 \def\keywords{embed flash movie LaTeX pdf 3d include sound swf mp3 video mp4 h.264 aac slideshow image gallery flv audio multimedia streamed media rtmp YouTube animation JavaScript pdfLaTeX dvips ps2pdf dvipdfmx XeLaTeX u3d prc Adobe Reader Foxit RichMedia annotation LuaLaTeX}
41 \hypersetup{
42 bookmarksnumbered,linktocpage,%breaklinks,
43 pdftitle={The media9 Package},
44 pdfsubject={Documentation},
45 pdfauthor={Alexander Grahn},
46 pdfkeywords={\keywords},
47 allcolors=blue
48 }
49 \usepackage[ocgcolorlinks]{ocgx2}
50
51 %\usepackage{listings}
52 \usepackage{minted}
53
54 \def\XeLaTeX{X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}}\kern-.125em\LaTeX}
55 \def\pXepLaTeX{(X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}})\kern-.125em\LaTeX}
56
57 \graphicspath{{files/}}
58 \addmediapath{files}
59
60 \hyphenation{Ja-va-Script}
61
62 \newsavebox{\keyshift}
63 \newsavebox{\spacebar}
64 \newsavebox{\COO}
65 \savebox{\COO}{$\overrightarrow{COO}$}
66 \newsavebox{\CtoC}
67 \savebox{\CtoC}{$\overrightarrow{C2C}$}
68
69 \renewcommand{\textfraction}{0.0}
70 \renewcommand{\topfraction}{1.0}
71 \renewcommand{\bottomfraction}{1.0}
72
73 \ifpdf\else
74 \makeatletter
75 \@latex@error{Please use pdfLaTeX to compile this documentation}
76 \makeatother
77 \fi
78
79 \def\parsedate#1/#2/#3\relax{
80 \def\year{#1}
81 \def\month{#2}
82 \def\day{#3}
83 }
84 \usepackage{siunitx}
85
86 \begin{document}
87 \makeatletter
88 %\title{The {\sffamily media9} Package\\Version \g@mix@version@tl}
89 \title{The {\sffamily media9} Package, v\g@mix@version@tl}
90 \expandafter\parsedate\g@mix@date@tl\relax %set current date to package date
91 \makeatother
92 \author{Alexander Grahn\\[1ex]\hypersetup{breaklinks=false}\url{https://gitlab.com/agrahn/media9}\hypersetup{breaklinks=true}}
93 \maketitle
94
95 \begin{abstract}\noindent
96 A \LaTeX{} package for embedding interactive Adobe Flash (SWF) and 3D files (Adobe U3D \& PRC) as well as video and sound files or streams (FLV, MP4/H.246, MP3) into PDF documents with Adobe Reader-9/X compatibility.\\[0.2\baselineskip]
97 \begin{sloppypar}\foreignlanguage{nil}{\noindent\emph{Keywords}: \keywords}\end{sloppypar}
98 \end{abstract}
99
100 \tableofcontents
101
102 \section{Introduction}
103 This package provides an interface to embed, in the first place, interactive Flash (SWF) and 3D objects (Adobe U3D \& PRC) into PDF documents. Video and audio files or streams in the popular MP4, FLV and MP3 formats can be embedded as well. However, a media player Flash component is required for playback, as will be explained shortly. Playback of multimedia files uses Adobe Flash Player, which was bundled with Adobe Reader 9 and 10 versions. Unfortunately, beginning with Adobe Reader 11, it must be installed as a separate plug-in.
104
105 Among the supported media types, video and sound files require an additional Flash (SWF) application for playback, which must be either embedded into the PDF or loaded at runtime from the internet. There are numerous such players, both open-source and commercial, available on the internet. One of them is the highly configurable open-source `StrobeMediaPlayback.swf'~\cite{strobe}, maintained by Adobe and hosted on \href{http://sourceforge.net/projects/osmf.adobe/files/}{SourceForge.net}. Package `media9' comes with an enhanced version of `StrobeMediaPlayback.swf'. In addition, two simple players for video and audio, `VPlayer.swf' and `APlayer.swf' are included, which can be used instead. They provide sufficient functionality for playing embedded files and streamed media.
106
107 There is yet another player bundled with `media9'. It is a simple image gallery viewer called `SlideShow.swf' which can display collections of embedded and remote images in the PNG, JPEG and GIF file formats. Remote images are downloaded at viewing time and can be configured to be refreshed at definite time intervals.
108
109 Flash Player supports the efficient H.264 codec for video compression. MP4/H.264 video files can be encoded from existing video files and from numbered bitmap sequences using the \verb+ffmpeg+ (\url{http://ffmpeg.org}) or \verb+avconv+ (\url{http://libav.org}) command line tools (Libav is a fork from the FFmpeg code). In order to allow for precise seeking within video files it is necessary to encode them with a sufficient number of key frames. The command line for recoding an existing video file \verb+video.avi+ into \verb+video.mp4+ reads (one line; \verb+ffmpeg+ can be substituted with \verb+avconv+)
110 \begin{center}
111 \begin{Verbatim}
112 ffmpeg -i video.avi -vf scale="trunc(iw/2)*2:trunc(ih/2)*2"
113 -c:v libx264 -profile:v high -pix_fmt yuv420p
114 -g 30 -r 30 video.mp4
115 \end{Verbatim}
116 \end{center}
117 From a sequence \verb+frame-0.png+, \verb+frame-1.png+, ... of bitmap files, an MP4 video is produced by
118 \begin{Verbatim}
119 ffmpeg -i frame-%d.png -vf scale="trunc(iw/2)*2:trunc(ih/2)*2"
120 -c:v libx264 -profile:v high -pix_fmt yuv420p
121 -g 30 -r 30 video.mp4
122 \end{Verbatim}
123 Both examples insert a key frame (option `\verb+-g+') at every second since the frame rate is set to 30 fps. The video encoder requires even pixel numbers in both dimensions which is ensured by adding `\verb+-vf scale="..."+' to the option list.
124
125 \emph{Note:} `media9' package replaces the now obsolete `movie15' package. `media9' is based on the RichMedia Annotation (Annotations are the interactive elements in a document, in PDF specification parlance.), an Adobe addition to the PDF specification~\cite{supplement}, while `movie15' uses the old multimedia framework (`Screen Annotation') of pre-9 Readers which depends on third-party plug-ins and which does not support recent media file formats.
126
127 Package `media9' supports the usual PDF making workflows, i.\,e. pdf\LaTeX{}, Lua\LaTeX, \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+/Distiller and \pXepLaTeX{} $\rightarrow$ \verb+(x)dvipdfmx+.
128
129 The final PDF can be viewed in current Adobe Readers on MS Windows and other platforms. On Unix platforms including Linux, however, support of Flash, video and sound was discontinued at Reader version 9.4.2, probably for security reasons. PDF documents which target \href{ftp://ftp.adobe.com/pub/adobe/reader/unix/9.x/9.4.1/}{Adobe Reader 9.4.1 for Linux} should use `VPlayer9.swf' and `APlayer9.swf' (also included in the `media9' package). These media player components are compatible with the older Flash Player 9 plugin that is bundled with the Reader for Linux. Recent versions of Foxit PDF Reader, which is available on the Windows platform, are known to render embedded Flash, video and audio content. Foxit also uses Adobe Flash Player plugin. On tablets and phones running Android or iOS, ezPDF Reader was reported to play video and sound files embedded with `media9'.
130
131 \section{Requirements}
132 \begin{trivlist}
133 \item l3kernel (\LaTeX{} package), version $\ge \ExplFileDate$
134 \item pdf\TeX{}, version $\ge1.40$
135 \item Ghostscript, version $\ge9.15$, or Adobe Distiller for PS to PDF conversion
136 \item dvipdfmx, version $\ge 20190503$ for DVI to PDF conversion
137 \item Adobe Reader, version $\ge9$, but not greater than 9.4.1 on Linux; Foxit Reader (Flash, video, audio)
138 \item Adobe Flash Player plugin for Firefox
139 \end{trivlist}
140
141 \section{Installation}
142 MiK\TeX{} and \TeX{}Live users should run the package manager for installation and updates.
143
144 Otherwise, a manual installation into the \emph{local} TeX-Directory-Structure (TDS) root directory is done along the following steps:
145 \begin{enumerate}
146 \item Download the TDS compliant package file `\href{http://mirror.ctan.org/install/macros/latex/contrib/media9.tds.zip}{media9.tds.zip}' from CTAN.
147 \item Find the local TDS root directory by running\\
148 {\tt\phantom{xx}kpsewhich -var-value TEXMFLOCAL}\\
149 on the command line. The local TDS root directory is intended for packages that are not maintained by the \TeX{}Live package manager.
150 \item Unzip `\verb+media9.tds.zip+' into the local TDS root directory previously found. Depending on the location of this directory, you may need to be logged in as Root/Administrator.
151 \item After installation, update the filename database by running `{\tt texhash}' on the command line. Again, Root/Administrator privileges may be required.
152 \end{enumerate}
153 For updating the package, repeat the steps given above.
154
155 \section{Using the package}\label{pkguse}
156 Invoke the package by putting the line
157 \begin{verbatim}
158 \usepackage[<package options>]{media9}
159 \end{verbatim}
160 to the preamble of your document, i.\,e. somewhere between \verb+\documentclass+ and \verb+\begin{document}+.
161
162 `media9' honours the package options:
163 \begin{verbatim}
164 dvipdfmx
165 xetex
166 bigfiles
167 draft
168 final
169 playbutton=...
170 noplaybutton
171 activate=...
172 deactivate=...
173 windowed=...
174 transparent
175 passcontext
176 attachfiles
177 3Dplaytype=...
178 3Dplaycount=...
179 3Dplayspeed=...
180 3Dtoolbar
181 3Dnavpane
182 3Dpartsattrs=...
183 3Dmenu
184 3Dbg=...
185 3Dlights=...
186 3Drender=...
187 \end{verbatim}
188 Except for `\verb+dvipdfmx+', `\verb+xetex+' and `\verb+bigfiles+', the options above are also available (among others) as command options and will be explained shortly. However, if used as package options they have global scope, taking effect on all embedded media in the document. In turn, command options locally override global settings. Options without an argument are boolean options and can be negated by appending `\verb+=false+'.
189
190 \XeLaTeX{} will be auto-detected. Therefore package option `\verb+xetex+' is optional. However, in the case of \verb+dvipdfmx+, package option `\verb+dvipdfmx+' is mandatory because it cannot be auto-detected.
191
192 \begin{animateinline}[autoplay,loop,nomouse]{1}\strut\emph{Important:}\newframe[3]\end{animateinline} If PDF is generated via DVI and Postscript by the command sequence \verb+latex+ $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+, \verb+dvips+ option `\verb+-Ppdf+' should \emph{not} be set when converting the intermediate DVI into Postscript. If you cannot do without, put `\verb+-D 1200+' \emph{after} `\verb+-Ppdf+' on the command line. Users of \LaTeX-aware text editors with menu-driven toolchain invocation, such as \TeX{}nicCenter, should check the configuration of the \verb+dvips+ call.
193
194 Option `\verb+bigfiles+' is only relevant for the \verb+latex+ $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+ workflow. It may be needed if large media files cause \verb+latex+ to abort with error `\Verb+TeX capacity+ \Verb+exceeded+'. See Sect.\ \ref{bugs}.\enlargethispage{2\baselineskip}
195
196
197 \section{The user interface}
198 Package `media9' provides commands for media inclusion (\verb+\includemedia+) and insertion of media control buttons (\verb+\mediabutton+). The latter is introduced in Sect. \ref{mbtn}.
199
200 \subsection{Media inclusion}
201 \begin{verbatim}
202 \includemedia[<options>]{<poster text>}{
203 <main Flash (SWF) file or URL | 3D (PRC, U3D) file>}
204 \end{verbatim}
205
206 The last argument, \verb+<main Flash (SWF) file or URL | 3D (PRC, U3D) file>+, is the main interactive application to be inserted into the PDF. In the case of Flash, this can be a local SWF file, or a URL, such as a YouTube video player. A local file will become part of the final PDF file, while Flash content from a URL requires an internet connection when the user activates it in Adobe Reader. A URL must be fully qualified, i.\,e., starting with either `\verb+http[s]://+' or `\verb+ftp://+'. As for 3D content, Adobe Reader only supports U3D or PRC files embedded in the PDF; they cannot be loaded or streamed during runtime. The most frequent use of \verb+\includemedia+ will likely be embedding video or sound files for playback in Adobe Reader. For this we need some media player, which is an SWF file we embed as our main application. It will be configured to load, upon activation, a particular video or sound file that was embedded as a resource into the PDF or is to be streamed from the internet. This will be shown later. Note that a local file (main application or resource) will only once be physically embedded in order to keep the final PDF file size small. If the same file (identified by MD5 checksum) appears in other \verb+\includemedia+ commands, only a reference will be inserted that points to the same storage location in the PDF.
207
208 Argument \verb+<poster text>+ defines the size of the rectangular region of the document page in which the media will be displayed. Moreover, \verb+<poster text>+ will be shown in case the media has not been activated.
209 %(Internally, \verb+<poster text>+ is put into a \LaTeX{} box, which is used as the appearance of the PDF annotation, i.\,e. the interactive region created by \verb+\includemedia+, in PDF specification parlance.)
210 \verb+<poster text>+ can be anything that \LaTeX{} can typeset, such as an \verb+\includegraphics+ command serving as a poster image, a PGF/TikZ/PSTricks inline graphics or just ordinary text. Alternatively, \verb+<poster text>+ can be left blank in which case the size of the media rectangle should be set with options `\verb+width+' and `\verb+height+'. If a non-zero size \verb+<poster text>+ was provided, it can be resized using any combination of options `\verb+width+', `\verb+height+' or `\verb+totalheight+', `\verb+keepaspectratio+' and `\verb+scale+'.
211
212 A list of directories where \TeX{} searches for media and resource files can be set-up by means of
213 \begin{verbatim}
214 \addmediapath{<directory>}
215 \end{verbatim}
216 This command appends one directory at a time to the search list. To specify more directories, just use it repeatedly. The path separator is always `\verb+/+', independent from the operating system.
217
218 The following section explains all command options provided. They are passed to the media inclusion command as a comma separated list enclosed in a pair of square brackets.
219
220 \subsection{Command options}
221 A subset of the command options (see Sect. \ref{pkguse}) can also be used as package options, which lets them apply to all embedded media. Some of the options listed here are meaningful only for a specific media type (either Flash or 3D), which will be noted explicitly if not obvious. Dedicated sections covering Flash, video and sound as well as 3D inclusion will follow later on in this document.
222
223 \begin{verbatim}
224 label=<label text>
225 \end{verbatim}
226 The media annotation is given a label, \verb+<label text>+, which should be unique. Labelled media annotations can be targeted by the media actions of a control button (see description of the \verb+\mediabutton+ command in Sect. ~\ref{mbtn}). Moreover, a reference to the RichMedia Annotation object (of type `\verb+AnnotRichMedia+') is assigned to the JavaScript variable \verb+annotRM['<label text>']+ in order to facilitate its access in JavaScript. Note that the JavaScript reference is known only after the first opening of the page containing the media.
227 \begin{verbatim}
228 width=<h-size>,
229 height=<v-size> | totalheight=<v-size>,
230 keepaspectratio
231 \end{verbatim}
232 Resize the media playback area. \verb+<poster text>+, if provided, is squeezed or stretched accordingly. If only one of `\verb+width+' or `\verb+[total]height+' is given, the other dimension is scaled to maintain the aspect ratio of \verb+<poster text>+. If both `\verb+width+' and `\verb+[total]height+' are given together with `\verb+keepaspectratio+', \verb+<poster text>+ is resized to fit within \verb+<h-size>+ and \verb+<v-size>+ while maintaining its original aspect ratio. Any valid \TeX{} dimension is acceptable for \verb+<h-size>+ and \verb+<v-size>+. In addition, the length commands \verb+\width+, \verb+\height+, \verb+\depth+ and \verb+\totalheight+ can be used to refer to the original dimensions of \verb+<poster text>+.
233 \begin{verbatim}
234 scale=<factor>
235 \end{verbatim}
236 Scales the playback area by \verb+<factor>+.
237 \begin{verbatim}
238 addresource=<local file>,
239 addresource=<another local file>,
240 ...
241 \end{verbatim}
242 Every invocation of this option embeds another local file that is required to run the main Flash application or 3D file (last argument of \verb+\includemedia+). Typically, this option is used to embed video files, media player skins, XML files (such as databases), additional objects to appear in a 3D scene etc. If an already embedded file is needed in another \verb+\includemedia+ command, this option must be given there again. However, the file in question will only once be physically embedded in order to keep the PDF file small.
243 \begin{verbatim}
244 flashvars={<some_var=some_val&another_var=another_val&...>}
245 \end{verbatim}
246 (Flash only) Usually, Flash applications can be configured via ActionScript (AS) variables the programmer of the application has made visible from outside. A typical use would be to set the video source of a media player to point to an embedded MP4 file or to a live stream, or to set the speaker volume for playback of an MP3 file. The argument of the \verb+flashvars+ option is a list of \verb+<AS variable>=<value>+ pairs separated by `\verb+&+' and enclosed in a pair of braces (\verb+{...}+).
247
248 Note: If a variable is to be set to point to an embedded resource, the value of the variable must be given in exactly the same way as with the `\verb+addresource+' option. Otherwise the name of the embedded file cannot be resolved. For example,
249 \begin{verbatim}
250 addresource=path/to/video.mp4
251 \end{verbatim}
252 implies
253 \begin{verbatim}
254 flashvars={vid=path/to/video.mp4&...}
255 \end{verbatim}
256 if, for a particular media player, the video source is set through ActionScript variable `\verb+vid+'.
257
258 (Note for 3D) Resource files used in 3D scenes cannot be loaded by means of ActionScript variables. This must be done by 3D JavaScript during activation of the 3D scene in the Reader. 3D JavaScript can be attached using option `\verb+add3Djscript+', see below.
259 \begin{verbatim}
260 attachfiles
261 \end{verbatim}
262 If set, embedded files can be downloaded from the PDF via the \Acrobatmenu{ShowHideFileAttachment}{Attachments} navigation pane in the Reader.
263 \begin{verbatim}
264 activate=onclick | pageopen | pagevisible
265 \end{verbatim}
266 Decides on how to activate the media annotation. `\verb+activate=onclick+' is default behaviour and does not need be given explicitly; embedded media is activated when the user clicks on it or by a JavaScript. It is recommended to provide a poster image with the \verb+<poster text>+ argument in that case. `\verb+pageopen+' and `\verb+pagevisible+' automatically activate the media when the page becomes visible; `{\tt pagevisible}' is better for two-up and continuous page display.
267 \begin{verbatim}
268 deactivate=onclick | pageclose | pageinvisible
269 \end{verbatim}
270 Decides on how to de-activate the media annotation. `\verb+deactivate=pageclose+' is default behaviour and does not need be given explicitly; media is automatically de-activated when the user leaves the page containing the media. `\verb+pageinvisible+' is similar, but may be better for two-up and continuous page display. Setting `\verb+deactivate+ \verb+=onclick+' requires user interaction for de-activating the media, either by right-click and chosing `\emph{\sffamily Disable Content}' or by a JavaScript.
271 \hypertarget{draftfinal}{}%
272 \begin{verbatim}
273 draft
274 final
275 \end{verbatim}
276 With `\verb+draft+' the media is not embedded. Instead, a box is inserted that has the dimensions of \verb+<poster text>+, subject to the resizing options `\verb+width+', `\verb+height+', `\verb+totalheight+' and `\verb+scale+'. Option `\verb+final+' does the opposite as it forces the media to be embedded. Both options can be used to reduce compilation time during authoring of a document. To get the most out of them it is recommended to set `\verb+draft+' globally as a package or class option and to set `\verb+final+' locally as a command option of the media annotation that is currently worked on. After the document has been finished, the global `\verb+draft+' option can be removed.
277 \begin{verbatim}
278 playbutton[= fancy | plain | none]
279 noplaybutton
280 \end{verbatim}
281 By default, a transparent play button is laid over the inactive media annotation to draw the reader's attention to the embedded multimedia content. It is provided in two versions, `\verb+fancy+' and `\verb+plain+', but only `\verb+plain+' is available in the \XeLaTeX{} workflow. The default setting is to try the `\verb+fancy+' version. `\verb+noplaybutton+' or `\verb+playbutton=none+' disable the play button overlay.
282 \begin{verbatim}
283 windowed[= false | [<width>x<height>][@<position>] ]
284 \end{verbatim}
285 The media is played in a floating window, instead of being played in an embedded fashion. The floating window size is specified via the optional argument \verb+<width>x<height>+, where \verb+<width>+ and \verb+<height>+ are given in pixels (integer numbers without unit). If the size is not given, a default size is guessed from the annotation size. Optionally, the position of the floating window on the screen can be specified through \verb+@<position>+, where \verb+<position>+ may assume one of `\verb+tl+', `\verb+cl+', `\verb+bl+', `\verb+bc+', `\verb+br+', `\verb+cr+', `\verb+tr+', `\verb+tc+' or `\verb+cc+'. The position specifiers have the following meaning:\quad{\fboxsep=1pt\fbox{\vtop{\hbox{\ttfamily\fbox{\rule{0pt}{1.5ex}tl} \fbox{\rule{0pt}{1.5ex}tc} \fbox{\rule{0pt}{1.5ex}tr}} \hbox{\ttfamily\fbox{\rule{0pt}{1.5ex}cl} \fbox{\rule{0pt}{1.5ex}cc} \fbox{\rule{0pt}{1.5ex}cr}} \hbox{\ttfamily\fbox{\rule{0pt}{1.5ex}bl} \fbox{\rule{0pt}{1.5ex}bc} \fbox{\rule{0pt}{1.5ex}br}}}}}\\[0.5ex]
286 Default window position is `\verb+cc+', that is, centred on the screen. `\verb+false+' can be set to override a global setting via package options.
287 \begin{verbatim}
288 transparent
289 \end{verbatim}
290 Indicates whether underlying page content is visible through transparent areas of the embedded media. Default is `\verb+transparent=false+'; media artwork is drawn over an opaque background prior to composition over the page content.
291 \begin{verbatim}
292 passcontext
293 \end{verbatim}
294 (Flash only) If set, user right-clicks are passed through to the context menu of the embedded Flash application, replacing the default Adobe Reader context menu. Useful for cases where the Flash programmer provided additional functionality through the context menu of his application.
295 \begin{verbatim}
296 3Dtoolbar
297 \end{verbatim}
298 Indicates whether a 3D toolbar should be shown in the Reader on top of the embedded 3D model.
299 \begin{verbatim}
300 3Dnavpane
301 \end{verbatim}
302 If set, the 3D navigation pane displaying the \Acrobatmenu{ShowHideModelTree}{3D Model Tree} becomes visible in the Reader when the content is initially activated.
303 \begin{verbatim}
304 3Dcoo=<x> <y> <z>
305 \end{verbatim}
306 \verb+<x> <y> <z>+ specify the positional vector $\overrightarrow{COO}$ of the centre of orbit of the virtual camera. Real numbers in fixed and floating point notation are accepted.
307 \begin{verbatim}
308 3Dc2c=<x> <y> <z>
309 \end{verbatim}
310 \verb+<x> <y> <z>+ specify a direction vector $\overrightarrow{C2C}$ of arbitrary length, originating in the centre of orbit and pointing to the virtual camera. Real numbers in fixed and floating point notation are accepted.
311 \begin{verbatim}
312 3Droll=<roll>
313 \end{verbatim}
314 Prescribes an initial camera roll around the optical axis (in clockwise direction, if \verb+<roll>+ is greater that zero); measured in degrees and given as fixed or floating point real number.
315 \begin{verbatim}
316 3Dc2w=<12 element camera-to-world matrix>
317 \end{verbatim}
318 This option directly sets the camera-to-world transformation matrix according to the PDF specification. This is an expert option to be used \emph{instead} of the `\verb+3Dc2c+', `\verb+3Dcoo+' and `\verb+3Droll+' options. Only fixed point real numbers are accepted.
319 \begin{verbatim}
320 3Dpsob=Min | Max | W | H
321 \end{verbatim}
322 Expert option which directly sets either the \verb+/PS+ entry in the case of perspective projection or the \verb+/OB+ entry in the case of orthographic projection to one of the four possible values. Default value is \verb+Min+.
323 \begin{verbatim}
324 3Droo=<r>
325 \end{verbatim}
326 \verb+<r>+ is a positive fixed or floating point number specifying the radius of orbit $ROO$ of the virtual camera. Good values can be found by means of the `\verb+3Dmenu+' option.
327 \begin{verbatim}
328 3Daac=<angle>
329 \end{verbatim}
330 This option sets the aperture angle of the camera, measured in degrees, for the perspective view mode. Fixed and floating point real numbers between 0 and 180 are admissible. A sensible value of 30 is pre-set by default. Larger values can be used to achieve wide-angle or fish-eye effects. See example~\ref{u3dex} in section~\ref{sec:3Dintro}. This option excludes the use of the `\verb+3Dortho+' option.
331 \begin{verbatim}
332 3Dortho[=<orthographic scaling factor>]
333 \end{verbatim}
334 Switches from the default perspective to orthographic view mode. In orthographic view, the 3D object is parallelly projected onto the virtual camera chip. The projected image is scaled by \verb+<orthographic scaling factor>+ before reaching the camera chip; default value is 1. The optimal value for the scaling factor is given by $1/D$, where $D$ is the diameter of the smallest enclosing sphere of the 3D object in World coordinate units. Fixed and floating point real numbers are accepted. The camera should be positioned outside the 3D object. For this, the radius of orbit (option `\verb+3Droo+') should be greater than $D/2$. Good values for orthographic scaling and orbital radius can easily be found by means of the `\verb+3Dmenu+' option. Option `\verb+3Dortho+' excludes the use of the `\verb+3Daac+' option.
335 \hypertarget{3dmenu}{}%
336 \begin{verbatim}
337 3Dmenu
338 \end{verbatim}
339 Mainly used during document authoring. Adds three entries, `\emph{\sffamily Generate Default View}', `\emph{\sffamily Get Current View}' and `\emph{\sffamily Cross Section}' to the context (right-click) menu of an activated 3D annotation. Moreover, it allows single parts or part groups of the scene to be scaled, translated and rotated against the remaining scene objects using the keyboard. Their new position can be saved in the current view (`\emph{\sffamily Get Current View}'). At first, parts to be modified must be highlighted by clicking either into the scene or into the \Acrobatmenu{ShowHideModelTree}{3D Model Tree} (the part's bounding box becomes visible). Then, arrow keys \keys{\arrowkeyleft}, \keys{\arrowkeyright} let the part spin around the vertical axis, and \keys{\arrowkeyup}, \keys{\arrowkeydown} tilt against it. In order to spin parts around their local up-axis, keep \keys{\ctrl} pressed while using \keys{\arrowkeyleft} and \keys{\arrowkeyright}. Keys \keys{X}, \keys{\shift+X}, \keys{Y}, \keys{\shift+Y}, \keys{Z}, \keys{\shift+Z} translate the selected part along the World axes, and \keys{S}, \keys{\shift+S} scale the part.
340
341 `\emph{\sffamily Generate Default View}' computes optimal camera settings such that the visible parts of the 3D scene fit tightly into the viewing area. The result is printed, formatted as a list of \verb+\includemedia+ options, into the JavaScript console. The calculation is based on the 3D object size and its position in the World coordinate system as well as the current viewing mode (perspective or orthographic).
342
343 `\emph{\sffamily Cross Section}' is a toggle switch to add or remove a cross section to or from the current view. If a part of the 3D scene was previously selected, the central rotating point of the cutting plane is put into the part's centre, otherwise into the target point of the camera. The cutting plane can be rotated around the vertical axis and tilted against its upright position using the arrow keys \keys{\arrowkeyleft}, \keys{\arrowkeyright}, \keys{\arrowkeyup} and \keys{\arrowkeydown}. Keys \keys{X}, \keys{\shift+X}, \keys{Y}, \keys{\shift+Y}, \keys{Z}, \keys{\shift+Z} move the cutting plane along the World axes, and \keys{S}, \keys{\shift+S} scale its size.
344
345 `\emph{\sffamily Get Current View}' writes camera settings, any part alterations, an optional cross section as well as part and scene rendering attributes of the current view into the JavaScript console. The output is a readily formatted \verb+VIEW+ section to be inserted into or appended to a file of predefined views. See option `\verb+3Dviews+'. All settings reachable via the `\emph{\sffamily Part Options}' and `\emph{\sffamily Viewing Options}' context menu items are written to the \verb+VIEW+ section.
346 \begin{verbatim}
347 3Dbg=<r> <g> <b>
348 \end{verbatim}
349 This option sets the background colour of the 3D scene. Only fixed point real numbers in the range from 0 to 1 are allowed for the colour components. Option `\verb+transparent+' may not be set at the same time.
350 \begin{verbatim}
351 3Dlights=<lighting scheme>
352 \end{verbatim}
353 Sets the default lighting scheme. The following values are honoured: `\verb+None+', `\verb+White+', `\verb+Day+', `\verb+Night+', `\verb+Hard+', `\verb+Primary+', `\verb+Blue+', `\verb+Red+', `\verb+Cube+', `\verb+CAD+', `\verb+HeadLamp+'. The default is to use the lighting scheme as specified within the 3D artwork.
354 \begin{verbatim}
355 3Drender=Solid | Transparent[:<opacity>] | ...
356 \end{verbatim}
357 \begin{flushleft}
358 Sets the default render mode of the scene. The following values are honoured: `\verb+Solid+', `\verb+SolidWireframe+', `\verb+Transparent+', `\verb+TransparentWireframe+', `\verb+BoundingBox+', `\verb+TransparentBoundingBox+', `\verb+TransparentBoundingBoxOutline+', `\verb+Wireframe+', `\verb+ShadedWireframe+', `\verb+HiddenWireframe+', `\verb+Vertices+', `\verb+ShadedVertices+', `\verb+SolidOutline+', `\verb+Illustration+', `\verb+ShadedIllustration+'. Options `\verb+Transparent+' and `\verb+TransparentWireframe+' take an optional value between 0 and 1 that controls the opacity of the rendered 3D object.
359 \end{flushleft}
360 \begin{verbatim}
361 3Dpartsattrs=restore | keep
362 \end{verbatim}
363 When the user selects another view from the list of predefined views (see option `\verb+3Dviews+'), attributes of individual parts, such as opacity, visibility, render mode,
364 translation in space,
365 which all can be set from within the Reader or by means of a file of predefined views, are reset to their original states as defined in the embedded 3D file, before any new part settings are applied. This default behaviour can be overridden by `\verb+3Dpartsattrs=keep+'. This will preserve current part attributes when the user selects another predefined 3D view in the Reader.
366 \hypertarget{3Dviews}{}%
367 \begin{verbatim}
368 3Dviews=<views file>
369 \end{verbatim}
370 Instead of or in addition to the default view (options `\verb+3Dcoo+', `\verb+3Dc2c+', `\verb+3Droll+', `\verb+3Droo+', `\verb+3Daac+', `\verb+3Dortho+'), further \emph{named views} can be predefined in an auxiliary file \verb+<views file>+. Besides the virtual camera position, it is possible to adjust the rendering attributes, such as visibility and transparency, as well as position and scaling of every single part in the 3D scene. Moreover, background colour and scene lighting can be set individually for every view. The additional views can later be selected either from a drop down list in the tool bar that is associated with the activated 3D object in the Reader or from the context menu of the 3D object.
371
372 The file \verb+<views file>+ is structured into view sections, one for every view:
373 \begin{verbatim}
374 VIEW[=<optional name>]
375 COO=<x> <y> <z>
376 C2C=<x> <y> <z>
377 ROLL=<roll>
378 % C2W=<camera-to-world matrix> % instead of COO, C2C and ROLL
379 ROO=<roo>
380 AAC=<aac>
381 % ORTHO[=<othographic scaling factor>] % instead of AAC
382 BGCOLOR=<r> <g> <b>
383 RENDERMODE=<render mode>
384 LIGHTS=<lighting scheme>
385 CROSSSECT
386 CENTER=<x> <y> <z>
387 NORMAL=<x> <y> <z>
388 OPACITY=<cutting plane opacity>
389 VISIBLE=true | false
390 PLANECOLOR=<r> <g> <b>
391 INTERSECTIONVISIBLE=true | false
392 INTERSECTIONCOLOR=<r> <g> <b>
393 SHOWTRANSPARENT=true | false
394 SECTIONCAPPING=true | false
395 END
396 PARTSATTRS=keep
397 PART=<part name as in the Model Tree (required, optional if UTF16NAME present)>
398 UTF16NAME=<part name as hex encoded Unicode string>
399 VISIBLE=true | false
400 OPACITY=<part opacity>
401 RENDERMODE=<part render mode>
402 TRANSFORM=<12 element transformation matrix>
403 END
404 PART=<...>
405 ...
406 END
407 etc.
408 END
409
410 VIEW
411 ...
412 END
413
414 etc.
415 \end{verbatim}
416 A view section starts with the keyword \verb+VIEW+, optionally followed by a name for the view, and ends with the keyword \verb+END+. If no name is given to the view, a default one is created, consisting of `View' followed by the number of the current \verb+VIEW+ section in the file. A \verb+VIEW+ section may contain optional entries for setting the camera position and global rendering attributes of the scene, a \verb+CROSSSECT+ subsection as well as \verb+PART+ subsections for setting rendering and other attributes of parts individually. Table~\ref{tab:views} lists the entries in a \verb+VIEW+ section.
417
418 Part sub-sections are opened by \verb+PART=<part name>+ and closed by \verb+END+. There may be as many part subsections as there are parts in a 3D scene. Table~\ref{tab:parts} lists the possible entries in a \verb+PART+ sub-section. All entries are optional. However, a \verb+UTF16NAME+ entry is recommended, as the part name may contain non-ASCII characters. The value of the \verb+UTF16NAME+ key is the part name as a hex-encoded Unicode string. If \verb+UTF16NAME+ is not used, the part name in the 3D file must be entirely composed of ASCII characters. In that case, \verb+<part name>+ is mandatory and must match the part name as indicated in the \Acrobatmenu{ShowHideModelTree}{3D Model Tree} of the 3D object (accessible via right-click onto the model in the Reader). The part can be scaled and repositioned by means of a \verb+TRANSFORM+ entry which takes a 12-element transformation matrix as its value. Remaining entries in a part sub-section control the visual appearance of the part.
419
420 A view section may contain at most one \verb+CROSSSECT+ sub-section. It inserts a cutting plane at a definite position and orientation in the 3D space, controlled by optional \verb+CENTER+ and \verb+NORMAL+ entries. The appearance characteristics of the cutting plane and the intersection of the plane with the 3D geometry are controlled by optional \verb+OPACITY+, \verb+VISIBLE+, \verb+PLANECOLOR+, \verb+INTERSECTIONVISIBLE+, \verb+INTERSECTIONCOLOR+,\\\verb+SHOWTRANSPARENT+, \verb+SECTIONCAPPING+ entries. See Table~\ref{tab:crosss} for explanation.
421
422 The views file can be commented. As usual, comments start with the percent sign.
423
424 To facilitate the creation of a views file, option `\verb+3Dmenu+' can be added to \verb+\includemedia+ (see above). It creates context (right-click) menu entry `Get Current View' which outputs a complete \verb+VIEW+ section corresponding to the current view of the 3D object in the Reader, including camera position, an optional cross section, and all part and viewing options that can be modified via the 3D toolbar (option `\verb+3Dtoolbar+') or the context menu of the 3D object (entries `\emph{\sffamily Part Options}', `\emph{\sffamily Viewing Options}'). Hence, apart from tweaking one or another entry, there should be no need for writing views files by hand.
425 \begin{verbatim}
426 3Dplaytype=linear | oscillating
427 \end{verbatim}
428 According to the PDF specification, embedded keyframe animations can be played in two ways. If set to `\verb+linear+', keyframe animations are driven linearly from beginning to end, while `\verb+oscillating+' lets the animation play in a forth-and-back manner.
429 \begin{verbatim}
430 3Dplaycount=<integer number>
431 \end{verbatim}
432 A non-negative \verb+<integer number>+ represents the number of times the animation is played. A negative integer indicates that the animation is infinitely repeated. This value is ignored if option \verb+3Dplaytype+ is not set.
433 \begin{verbatim}
434 3Dplayspeed=<positive number>
435 \end{verbatim}
436 This option can be used to adjust the keyframe animation speed. A value of `1' corresponds to the default speed defined in the 3D file.
437 \hypertarget{add3Djscript}{}%
438 \begin{verbatim}
439 add3Djscript=<3D JavaScript file>,
440 add3Djscript=<another 3D JavaScript file>,
441 ...
442 \end{verbatim}
443 Things like animation, lighting, background of 3D objects etc. may also be script driven. Every invocation of `\verb+add3Djscript+' associates another JavaScript file with the 3D object. Upon activation of the 3D object, the scripts are executed once in the order of their inclusion. Refer to the Acrobat 3D JavaScript Reference~\cite{jscript3D} for syntax details. The following 3D JavaScript loads an image file that was attached by `\verb+addresource=images/sunset.jpg+' and uses it as the scene background.
444 \begin{verbatim}
445 sunset = new Image(new Resource('pdf://images/sunset.jpg'));
446 reh = new RenderEventHandler();
447 reh.onEvent = function(event) {
448 runtime.removeEventHandler(this);
449 event.canvas.background.image=sunset;
450 }
451 runtime.addEventHandler(reh);
452 \end{verbatim}
453 \hypertarget{3dscripts}{}For convenience, subdirectory `javascript' of the `media9' installation contains three 3D JavaScript files which may come in handy at times: `animation.js' enables embedded keyframe animation in 3D files; `3Dspintool.js' enables the Spin tool of the 3D plugin for easier rotating the 3D object with the mouse; `asylabels.js' adds `billboard behaviour' to text labels in Asymptote ($\ge v2.17$) generated PRC files for improved visibility; text labels always face the camera while rotating the 3D object with the mouse.
454
455 \begin{table}[bp]%[p]%[htbp]
456 \centering
457 \caption{Entries in a {\tt VIEW} section.}\label{tab:views}
458 \begin{tabular}[t]{p{0.24\linewidth}lp{0.42\linewidth}}\hline
459 key & type & remarks\\\hline\hline
460 {\tt COO} & three numbers & centre of orbit, see option `{\tt 3Dcoo}'\\
461 {\tt C2C} & three numbers & centre of orbit to camera vector, see option `{\tt 3Dc2c}'\\
462 {\tt ROO} & number & radius of orbit, see option `{\tt 3Droo}'\\
463 {\tt C2W} & 12 numbers & camera-to-world transformation matrix, see option `{\tt 3Dc2w}'\\
464 {\tt AAC} & number & camera aperture angle, see option `{\tt 3Daac}'\\
465 {\tt ORTHO} & number (optional) & enables orthographic view, see option `{\tt 3Dortho}'\\
466 {\tt PSOB} & string & expert setting, see option `{\tt 3Dpsob}'\\
467 {\tt ROLL} & number & camera roll, see option `{\tt 3Droll}'\\
468 {\tt BGCOLOR} & three numbers & given as {\tt<r> <g> <b>}, specify the 3D scene background colour (RGB), see option `{\tt 3Dbg}'\\
469 {\tt RENDERMODE} & string & render mode of the 3D object, see option `{\tt 3Drender}'\\
470 {\tt LIGHTS} & string & lighting scheme, see option `{\tt 3Dlights}'\\
471 {\tt PARTSATTRS} & string & allowed values are `{\tt keep}' and `{\tt restore}'; decides on whether to restore or not original part attributes before applying new ones from this view; see option `{\tt 3Dpartsattrs}'\\
472 {\tt PART}\,\,(sub-sec\-tion) & string & part name as in the \Acrobatmenu{ShowHideModelTree}{3D Model Tree}; name argument is optional if a {\tt UTF16NAME} entry is present in the sub-section opened by a {\tt PART} keyword, otherwise required; see Table~\ref{tab:parts} for list of possible entries\\
473 {\tt CROSSSECT}~(sub-section) & -- & see Table~\ref{tab:crosss} for list of possible entries\\
474 \hline
475 \end{tabular}
476 \end{table}
477
478 \begin{table}%[p]%[htbp]
479 \centering
480 \caption{Entries in a {\tt PART} sub-section.}\label{tab:parts}
481 \begin{tabular}[t]{llp{0.5\linewidth}}\hline
482 key & type & remarks\\\hline\hline
483 {\tt UTF16NAME} & hex string & part name in UTF-16 (aka Unicode), encoded as a hexadecimal string; optional, but useful for part names composed of non-latin characters;\\
484 {\tt VISIBLE} & boolean & a flag (`{\tt true}' or `{\tt false}') indicating the visibility of this part\\
485 {\tt OPACITY} & number & a number between 0.0 and 1.0 specifying the opacity of this part\\
486 {\tt RENDERMODE} & string & rendermode of this part, overrides global {\tt RENDERMODE} value in parent {\tt VIEW} section, see option `{\tt 3Drender}'\\
487 {\tt TRANSFORM} & 12 numbers & transformation matrix defining the part's position and scaling\\
488 \hline
489 \end{tabular}
490 \end{table}
491
492 \begin{table}%[p]%[htbp]
493 \centering
494 \caption{Entries in a {\tt CROSSSECT} sub-section.}\label{tab:crosss}
495 \begin{tabular}[t]{llp{0.5\linewidth}}\hline
496 key & type & remarks\\\hline\hline
497 {\tt CENTER} & three numbers & central point coordinates of the cutting plane\\
498 {\tt NORMAL} & three numbers & normal vector coordinates of the cutting plane pointing into the cut-off region\\
499 {\tt OPACITY} & number & a number between 0.0 and 1.0 specifying the opacity of the cutting plane\\
500 {\tt VISIBLE} & boolean & a flag (`{\tt true}' or `{\tt false}') indicating the visibility of the cutting plane\\
501 {\tt PLANECOLOR} & three numbers & given as {\tt<r> <g> <b>}, specify the colour (RGB) of the cutting plane\\
502 {\tt INTERSECTIONVISIBLE} & boolean & a flag (`{\tt true}' or `{\tt false}') indicating the visibility of the intersection of the cutting plane with any 3D geometry\\
503 {\tt INTERSECTIONCOLOR} & three numbers & given as {\tt<r> <g> <b>}, specify the colour (RGB) for the cutting plane's intersection with the 3D geometry\\
504 {\tt SHOWTRANSPARENT} & boolean & a flag (`{\tt true}' or `{\tt false}') indicating that the portion of a model on the cut side of a section plane shall be viewed using a transparent render mode\\
505 {\tt SECTIONCAPPING} & boolean & a flag (`{\tt true}' or `{\tt false}') indicating whether the section plane shall be closed and rendered as if cutting through a solid object\\
506 \hline
507 \end{tabular}
508 \end{table}
509
510 \clearpage
511 \subsection{Control buttons}\label{mbtn}
512 \begin{verbatim}
513 \mediabutton[<options>]{<normal button text or graphic>}
514 \end{verbatim}
515 This command inserts a clickable button for media control. Actions to be performed are specified through options `\verb+mediacommand+', `\verb+3Dgotoview+' and `\verb+jsaction+'. By using these options repeatedly and in any combination, several actions can be bound to one media button, and one media button can be used to control several media at the same time. Media actions are started in the given order but performed in parallel, because they do not wait for each other to finish. The target of an action is specified via the label that was also given to a particular media by the `\verb+label+' option of `\verb+\includemedia+'. Individual button faces can be defined for the `mouse-over' and `mouse-button-down' events using the `\verb+overface+' and `\verb+downface+' options. Without options, the button produced does nothing. The options provided are as follows:
516 \begin{verbatim}
517 overface=<mouse-over text or graphic>
518 \end{verbatim}
519 If specified, the media button changes its appearance when the mouse pointer is moved over it. Without this option, the button appearance does not change. An \verb+\includegraphics+ command may need to be enclosed in braces.
520 \begin{verbatim}
521 downface=<mouse-button-down text or graphic>
522 \end{verbatim}
523 If specified, the media button changes its appearance when the mouse button is pressed while the pointer is over it. An \verb+\includegraphics+ command may need to be enclosed in braces.
524 \begin{verbatim}
525 tooltip=<tip text>
526 \end{verbatim}
527 A box with \verb+<tip text>+ is shown when the mouse pointer is moved over the button.
528 \begin{verbatim}
529 3Dgotoview=<label text>[:<view specification>]
530 \end{verbatim}
531 Selects a view from the list of predefined views associated with a 3D media inclusion (see option `\verb+3Dviews+'). The target media is specified by \verb+<label text>+, as defined by the `\verb+label+' option of `\verb+\includemedia+'. \verb+<label text>+ alone without a view specification simply activates the 3D object if not yet activated. {\tt<view specification>} which is separated from the label by a colon (\verb+:+) can be one of the following: an integer specifying the zero-based index into the list of views in the 3D views file; one of `\verb+D+', `\verb+F+', `\verb+L+', `\verb+N+', `\verb+P+' indicating the default, first, last, next or previous view in the list of views; a string delimited by `\verb+(+' and `\verb+)+' matching the name of a view as specified by the `\verb+VIEW=...+' entry in the views file. The option can be given several times to simultaneously change the view in more than one 3D inclusion. However, it cannot be used to create an animation effect within the same 3D inclusion, because \verb+3Dgotoview+ actions are executed in parallel.
532 %For this, one may implement a 3D JavaScript function that is associated with the media button using the `\verb+mediacommand+' option.
533 \begin{verbatim}
534 mediacommand=<label text>[:<command> [(<arg1>) (<arg2>) ...]]
535 \end{verbatim}
536 A media command \verb+<command>+, with arguments if required, is sent to a media inclusion identified by \verb+<label text>+, as defined by the `\verb+label+' option of `\verb+\includemedia+'. \verb+<label text>+ alone without a command specification simply activates the media, if not yet activated. The option can be used multiple times within the same button to target different media inclusions at the same time or to execute several commands for the same media. Depending on the type of the target media (3D or Flash), \verb+<command>+ is either the name of a JavaScript function defined in a 3D JavaScript file associated with the 3D media (see option `\verb+add3Djscript+') or the name of an ActionScript function that was exposed by the embedded Flash file. ActionScript functions are exposed to the scripting context of the hosting document by using the \verb+ExternalInterface+ call within the Flash file. Arguments to be passed to \verb+<command>+ must be enclosed in `\verb+(+' and `\verb+)+' and separated by spaces, the whole list be finally enclosed in `\verb+[+' and `\verb+]+', even if there is only a single argument. Arguments can be of Boolean type (\verb+true+, \verb+false+), numbers (integer, reals) and strings. The number of arguments and their types must match the definition of the function to be called. Media players VPlayer.swf and APlayer.swf shipping with `media9' expose a number of ActionScript functions that can be used with this option (see Tab. \ref{AVPlayerMethods}). \verb+<command> [(<arg1>) (<arg2>) ...]+ must be enclosed in braces if there are embedded equals signs or commas. Examples of using `\verb+mediacommand+' are given in Figs.~\ref{videoa} and \ref{radio}c.
537 \begin{verbatim}
538 jsaction=[<label text>:]{<JavaScript code>}
539 \end{verbatim}
540 The JavaScript code is executed in the context of the document's instance of the JavaScript engine (there is one instance of the JavaScript engine per open document in Adobe Reader). \verb+<JavaScript code>+ is required and must be enclosed in braces. Unlike media actions defined with options `\verb+mediacommand+' and `\verb+3Dgotoview+', the JavaScript action defined here is not targeted at a particular embedded media and can be used to run arbitrary code. Therefore, \verb+<label text>+ is optional. If provided, it must be separated from \verb+<JavaScript code>+ by a colon. However, it is recommended to provide a label text. It ensures that \verb+annotRM['<label text>']+ is a valid JavaScript reference to the \verb+AnnotRichMedia+ object. \verb+annotRM['<label text>']+ can be used to get access to the global context of the annotation's instance of the 3D JavaScript engine (there is one instance of the 3D JavaScript engine per activated RichMedia Annotation with 3D content). The 3D JavaScript context of a 3D model can be accessed as \verb+annotRM['<label text>'].context3D+. Refer to the Acrobat 3D JavaScript Reference~\cite{jscript3D} for details on built-in JavaScript objects that are available in the 3D context. The \verb+annotRM['<label text>'].callAS()+ method may be used as an alternative to the `\verb+mediacommand+` option. Both serve as means of running ActionScript functions exposed by embedded Flash files. See~\cite{jscript} for details.
541 \begin{verbatim}
542 draft
543 final
544 \end{verbatim}
545 See \hyperlink{draftfinal}{above}.
546
547 \clearpage
548 \section[Embedding Flash, video and sound, image slide-shows (with examples)]{Embedding Flash, video and sound,\\ image slide-shows}
549 A YouTube video clip, as shown in Fig.~\ref{alien}, may serve as a basic example of loading Flash content from a URL to be displayed in an embedded fashion in a PDF document. Indeed, a YouTube clip is nothing more than a small SWF file which loads a video stream and other necessary resources, such as user controls and a player skin from a remote server. It can be configured via ActionScript variables to play several videos in a row, to play a video in a loop etc. Player parameters are documented on \url{http://code.google.com/apis/youtube/player_parameters.html} and can be passed to the player using either the `\verb+flashvars+' option, as in the example, or appended to the URL string after the video ID. A question mark `\verb+?+' must be put between the video ID and the parameter string. Some of the documented parameters, such as `\verb+rel+', seem to have an effect only if they are passed as part of the URL.
550
551 \begin{figure}[H]
552 \centering
553 \begin{Verbatim}
554 \includemedia[
555 width=0.6\linewidth,height=0.3375\linewidth, % 16:9
556 activate=pageopen,
557 flashvars={
558 modestbranding=1 % no YT logo in control bar
559 &autohide=1 % controlbar autohide
560 &showinfo=0 % no title and other info before start
561 &rel=0 % no related videos after end
562 }
563 ]{}{http://www.youtube.com/v/r382kfkqAF4?rel=0}
564 \end{Verbatim}
565 \vspace{1ex}
566 \includemedia[
567 width=0.6\linewidth,height=0.3375\linewidth,
568 activate=pageopen,
569 flashvars={
570 modestbranding=1 % no YT logo in control bar
571 &autohide=1 % controlbar autohide
572 &showinfo=0 % no title and other info before start
573 &rel=0 % no related videos after end
574 }
575 ]{}{http://www.youtube.com/v/r382kfkqAF4?rel=0}
576 \caption{A YouTube video as an example of a Flash application loaded from a URL.}\label{alien}
577 \end{figure}
578
579 Media files (video, sound, images) are always loaded and then played by a media player application. Four players are installed along with the `media9.sty' package file: three simple players for video (`VPlayer.swf'), sound (`APlayer.swf') and slide-shows of embedded and/or remote (live or static) image files (`SlideShow.swf'), and the fully blown third-party media player `StrobeMediaPlayback.swf' with some fixes to improve its usability. The simple players are `chromeless', that is, they do not have graphical user controls. Nevertheless, interactivity is provided through left mouse button press and release for playing, pausing, resuming playback, through the player's context menu (right-click), and through the keyboard as summarized in Table \ref{kbcontrol}. The player apps were compiled using the open-source Apache Flex SDK~\cite{flex} from XML source files which reside in the \verb+doc/+ folder of the package installation. For `StrobeMediaPlayback.swf', only a patch file is included, as the sources can be downloaded elsewhere.
580
581 The improvements of `StrobeMediaPlayback.swf' in comparision to the original version on SourceForge.net are
582 \begin{itemize}
583 \item fix: video could not be restarted after end of playback if ActionScript variable `{\tt autoRewind}' is set to `{\tt false}'
584 \item new: first frame of video is shown as default poster instead of black stage
585 \item new: play/pause video by clicking on the stage (as with `VPlayer.swf'), useful in a lecture situation
586 \end{itemize}
587
588 There is no need to copy the installed players into the directory of the document source for embedding. They will be found by \LaTeX{} without taking any further action.
589
590 Like YouTube videos, media players are configured via ActionScript variables which are passed using option `\verb+flashvars+'. Table~\ref{playerparams} lists parameters available for `VPlayer.swf', `APlayer.swf' and `SlideShow.swf', Table~\ref{smpparams} for `StrobeMediaPlayback.swf'.
591
592 Playback of embedded video files is shown in Fig.~\ref{videoa}. Besides embedded files, also video streamed from remote servers via HTTP and RTMP protocols is supported, as shown in Fig.~\ref{videob}.
593
594 Sound files and streams in the MP3 format can be played with `APlayer.swf'. Fig.~\ref{radio} contains examples of an audio live stream and a remote MP3 sound file. In one of the sound examples, the player is loaded from a CTAN mirror during runtime because an internet connection is required anyway for streaming the audio. If a local sound file is to be embedded into the PDF this would have to be done in the same way as with the video file in one of the previous examples using the `\verb+addresource+' option.
595
596 The slide-show application `SlideShow.swf' requires a configuration file in the XML file format. It specifies the URLs from which the images will be loaded and may contain optional settings, such as image captions, refresh intervals for live images and initial rotation. The syntax is documented in the configuration file template in Fig.~\ref{SlideShowXML}. The file name of a configuration file is passed to `SlideShow.swf' using the `\verb+xml+' ActionScript variable. Note that for security reasons the configuration file and `SlideShow.swf' must reside on the same server or be both embedded into the PDF. Otherwise, a security error will be thrown by the Flash Player plugin. A slide-show example is shown in Fig.~\ref{slideshowex}.
597
598 `VPlayer.swf', `APlayer.swf' and `SlideShow.swf' expose a number of ActionScript functions to the JavaScript engine of Adobe Reader, allowing for playback control of media through push buttons (see Sect. \ref{mbtn}) and various trigger events. The functions and their calling convention are listed in Tables~\ref{AVPlayerMethods} and~\ref{SlideShowMethods}. From within JavaScript, these functions can be called using the `\verb+callAS+' (=~call ActionScript) method of the \verb+AnnotRichMedia+ object. As an example, a call to the `\verb+seek+' function looks like
599 \begin{verbatim}
600 annotRM.myvideo.callAS("seek", 12.3);
601 \end{verbatim}
602 and a call to the parameter-less function `\verb+playPause+' like
603 \begin{verbatim}
604 annotRM.myvideo.callAS("playPause");
605 \end{verbatim}
606 Both functions calls are sent to the media inclusion that was labelled `\verb+myvideo+' using the `\verb+label+' option of \verb+\includemedia+. An example of playing and pausing a video clip and setting the video source via interactive push buttons is given in Fig.~\ref{videoa}.
607
608 \begin{table}[htbp]
609 %\flushright
610 \centering
611 \caption{Keyboard control of media players (a) `VPlayer.swf' \& `APlayer.swf', (b) `SlideShow.swf'. Players must have the focus to take effect. Click onto the players if necessary.}\label{kbcontrol}
612 \vspace{3ex}
613 (a)\\
614 \begin{tabular}{rp{0.5\linewidth}}\hline
615 keys & action\\\hline\hline
616 \keys{\unexpanded{\makebox[2\width][c]{Space}}} & play/pause\\
617 \keys{Home}, \keys{End} & go to start/end\\
618 \keys{\arrowkeyleft}, \keys{\arrowkeyright} & seek backwards/forwards\\
619 \keys{\arrowkeydown}, \keys{\arrowkeyup} & decrease/increase speaker volume\\
620 \keys{m} & mute/unmute\\
621 \keys{\ctrl+\arrowkeyleft}, \keys{\ctrl+\arrowkeydown}, \keys{\ctrl+\arrowkeyright} & (APlayer.swf only) change sound speaker balance\\\hline
622 \end{tabular}
623
624 \vspace{6ex}
625 (b)\\
626 \begin{tabular}{rp{0.5\linewidth}}\hline
627 keys & action\\\hline\hline
628 \keys{\unexpanded{\makebox[2\width][c]{Space}}} & play/pause auto-cycling through slides\\
629 \keys{\arrowkeyleft}, \keys{\arrowkeyright} & previous/next slide\\
630 \keys{Home}, \keys{End} & go to first/last slide\\
631 \keys{r}, \keys{R} & right/left rotate current slide by \SI{90}{\degree}\\\hline
632 \end{tabular}
633 \end{table}
634
635 \begin{table}[tp]
636 \centering
637 \caption{Parameters (ActionScript variables) for media players (a) `VPlayer.swf' \& `APlayer.swf', (b) `SlideShow.swf' shipping with media9. Parameters are passed as a `{\tt\&}'-separated string using `{\tt flashvars}' option.}\label{playerparams}
638 \vspace{3ex}
639 (a)\\
640 \begin{tabular}[c]{p{0.4\linewidth}p{0.5\linewidth}}\hline
641 parameter & description\\\hline\hline
642 {\tt source=<file path or URL>} & (required) path to embedded media file (see option `{\tt addresource}'), or URL (http, rtmp) to online media file\\
643 {\tt autoPlay=true|false} & if {\tt=true}, automatically starts playback after activation (see option `{\tt activation})'\\
644 {\tt autoRewind=true|false} &(VPlayer.swf only) if {\tt=true}, automatically rewind to the first frame after playback has finished; default is `{\tt false}'\\
645 {\tt loop=true|false} & if {\tt=true}, media is played in a loop\\
646 {\tt scaleMode=letterbox|none| \phantom{.}\hfill{}stretch|zoom} & default: {\tt letterbox}; determines how to scale the video in order to fit into player\\
647 {\tt hideBar=true|false} &(APlayer.swf only) if {\tt=true}, the progress bar indicating the play position is not shown\\
648 {\tt volume=<value between 0.0 \phantom{.}\hfill{}and 1.0>} & sets volume of the sound\\
649 {\tt balance=<value between \phantom{xxxx} \phantom{.}\hfill{}-1.0 and 1.0>} & (APlayer.swf only) sets balance of sound speakers\\\hline
650 \end{tabular}
651
652 \vspace{6ex}
653 (b)\\
654 \begin{tabular}[c]{p{0.4\linewidth}p{0.5\linewidth}}\hline
655 parameter & description\\\hline\hline
656 {\tt xml=<file path or URL>} & (required) path to embedded (option `{\tt addresource}') or URL of remote configuration file\\
657 {\tt delay=<number>} & sets time delay in seconds for transition between slides during playback, default: \SI{5}{\second}\\
658 {\tt autoPlay=true|false} & if {\tt=true}, automatically starts cycling through slides after activation (see option `{\tt activation})'\\\hline
659 \end{tabular}
660 \end{table}
661
662 \begin{table}%[bp]
663 \centering
664 \caption{Exposed ActionScript functions of media players `VPlayer.swf' and `APlayer.swf' that can be called from within media buttons (see Sect. \ref{mbtn}) or from JavaScript using the `{\tt callAS}' method of the `{\tt AnnotRichMedia}' JavaScript object (see~\cite{jscript} for further information).}\label{AVPlayerMethods}
665 \begin{tabular}[t]{lp{0.25\linewidth}p{0.5\linewidth}}\hline
666 function & argument &description\\\hline\hline
667 {\tt play} & number (optional) & play media, optionally starting at \emph{number} seconds offset into the media file\\
668 {\tt pause} & number (optional) & pause media, optionally at the given offset of \emph{number} seconds into the media file\\
669 {\tt playPause} & & toggle between play and pause\\
670 {\tt setSource} & string & load another media file (path to file, embedded using option `{\tt addresource}', or URL)\\
671 {\tt seek} & number & move the play location to a time offset from the beginning of the media; argument measured in seconds\\
672 {\tt rewind} & & rewind media to the beginning (without pausing it)\\
673 {\tt volume} & number between 0 and 1 & set volume level\\
674 {\tt balance} & number between $-1$ and $+1$ & (APlayer.swf only) set speaker balance\\
675 {\tt mute} & & mute or unmute (toggle) the audio of the media\\
676 {\tt currentTime}& & returns current playhead position in seconds; only useful in JavaScript via `{\tt callAS}' method\\
677 {\tt duration} & & returns duration of the media video/sound file currently loaded, only useful in JavaScript via `{\tt callAS}' method\\
678 {\tt playing} & & returns boolean value `{\tt true}', if the media is currently playing, `{\tt true}' otherwise; only useful in JavaScript via `{\tt callAS}' method\\
679 {\tt muted} & & returns boolean value `{\tt true}', if the sound is currently muted, `{\tt false}' otherwise; only useful in JavaScript via `{\tt callAS}' method\\\hline
680 \end{tabular}
681 \end{table}
682
683 \begin{table}%[bp]
684 \centering
685 \caption{Exposed ActionScript functions of slide-show player `SlideShow.swf' that can be called from within media buttons or from JavaScript.}\label{SlideShowMethods}
686 \begin{tabular}[t]{lp{0.21\linewidth}p{0.47\linewidth}}\hline
687 function & argument &description\\\hline\hline
688 {\tt play} & & play slide-show\\
689 {\tt pause} & & pause slide-show\\
690 {\tt playPause} & & toggle between play and pause\\
691 {\tt setXML} & string & load another configuration file (path to file, embedded using option `{\tt addresource}', or URL)\\
692 {\tt seek} & int number & go to slide `number' (zero-based)\\
693 {\tt slideNum} & & returns current slide number (zero-based); only useful in JavaScript via `{\tt callAS}' method\\
694 {\tt numSlides} & & returns total number of slides in the slide-show; only useful in JavaScript via `{\tt callAS}' method\\
695 {\tt playing} & & returns boolean value `{\tt true}', if the slide-show is currently playing, `{\tt true}' otherwise; only useful in JavaScript via `{\tt callAS}' method\\
696 {\tt rotate} & int number (optional) & rotate current slide by number$\times\SI{90}{\degree}$\\\hline
697 \end{tabular}
698 \end{table}
699
700 \begin{table}[bp]
701 \centering
702 \caption{Parameters (ActionScript variables) for `StrobeMediaPlayback.swf' shipping with media9. Parameters are passed as a `{\tt\&}'-separated string using `{\tt flashvars}' option.}\label{smpparams}
703 \begin{tabular}[t]{p{0.4\linewidth}p{0.5\linewidth}}\hline
704 parameter & description\\\hline\hline
705 {\tt src=<file path or URL>} & (required) path to embedded media file (see option `{\tt addresource}'), or URL (http, rtmp) of online media file\\
706 {\tt autoPlay=true|false} & default: {\tt false}; if {\tt=true}, automatically starts playback after activation (see option `{\tt activation})'\\
707 {\tt autoRewind=true|false} & default: {\tt true}; if {\tt=false}, keep last frame after end of playback\\
708 {\tt loop=true|false} & if {\tt=true}, media is played in a loop\\
709 {\tt scaleMode=letterbox|none| \phantom{.}\hfill{}stretch|zoom} & default: {\tt letterbox}; determines how to scale the video in order to fit into player\\
710 {\tt controlBarMode=docked|\phantom{xxxxxxxxxxxxxx} \phantom{.}\hfill{}floating|none} & default: {\tt docked}; determines position and visibility of control bar\\
711 {\tt controlBarAutoHide=\phantom{xxxxxxx} \phantom{.}\hfill{}true|false} & default: {\tt true}; automatically hide or not control bar\\
712 {\tt controlBarAutoHideTimeout= \phantom{.}\hfill{}<number [s]>} & default: {\tt 3}; time span before auto-hide\\
713 {\tt volume=<value between 0.0 \phantom{.}\hfill{}and 1.0>} & sets volume of the sound\\
714 {\tt audioPan=<value between \phantom{xxxx} \phantom{.}\hfill{}-1.0 and 1.0>} & default: {\tt 0}; sets balance of sound speakers\\
715 {\tt muted=true|false} & default: {\tt false}; mute or not sound\\
716 %{\tt clipStartTime=<number [s]>} & default: {\tt NaN}; time to start from\\
717 %{\tt clipEndTime=<number [s]>} & default: {\tt NaN}; time to end at\\
718 \hline
719 \end{tabular}
720 \end{table}
721
722 \begin{figure}[p]
723 \centering
724 \begin{Verbatim}
725 \includemedia[
726 label=some_dice,
727 width=0.6\linewidth,height=0.45\linewidth,
728 addresource=random.mp4, %two video files
729 addresource=cube.mp4,
730 transparent, %transparent player background
731 activate=pageopen,
732 passcontext, %show VPlayer's right-click menu
733 flashvars={
734 source=random.mp4
735 &loop=true % loop video
736 }
737 ]{}{VPlayer.swf}
738
739 \mediabutton[
740 mediacommand=some_dice:playPause,
741 overface=\color{blue}{\fbox{\strut Play/Pause}},
742 downface=\color{red}{\fbox{\strut Play/Pause}}
743 ]{\fbox{\strut Play/Pause}}
744 \mediabutton[
745 mediacommand=some_dice:setSource [(random.mp4)]
746 ]{\fbox{\strut random.mp4}}
747 \mediabutton[
748 mediacommand=some_dice:setSource [(cube.mp4)]
749 ]{\fbox{\strut cube.mp4}}
750 \end{Verbatim}
751 \vspace{1ex}
752 \makebox[\linewidth]{\hfill\includemedia[
753 label=some_dice,
754 width=0.6\linewidth,height=0.45\linewidth,
755 addresource=random.mp4, %two video files
756 addresource=cube.mp4,
757 transparent, %transparent player background
758 activate=pageopen,
759 passcontext, %show VPlayer's right-click menu
760 flashvars={
761 source=random.mp4
762 &loop=true % loop video
763 }
764 ]{}{VPlayer.swf}\hfill}
765 \makebox[\linewidth]{\hfill%
766 \mediabutton[
767 mediacommand=some_dice:playPause,
768 overface=\color{blue}{\fbox{\strut Play/Pause}},
769 downface=\color{red}{\fbox{\strut Play/Pause}}
770 ]{\fbox{\strut Play/Pause}}
771 \mediabutton[
772 mediacommand=some_dice:setSource [(random.mp4)]
773 ]{\fbox{\strut random.mp4}}
774 \mediabutton[
775 mediacommand=some_dice:setSource [(cube.mp4)]
776 ]{\fbox{\strut cube.mp4}}
777 \hfill}
778 \caption{Example of playing back two different embedded MP4 video files in the same video player instance. The player, `VPlayer.swf', is also embedded in the PDF. Exposed ActionScript functions `{\tt playPause}' and `{\tt setSource}' of `VPlayer.swf' (Table~\ref{AVPlayerMethods}) are used to set-up media control buttons. Different button faces have been defined for the Play/Pause button. Also, playback can be contolled via the player's context (right-click) menu or the keyboard.}\label{videoa}
779 \end{figure}
780
781 \begin{figure}%[bp]
782 \thispagestyle{empty}
783 \centering
784 %\lstinputlisting[basicstyle=\scriptsize\ttfamily,language=XML]{config.xml}
785 \vspace{-10\baselineskip}
786 \hskip -5em\inputminted[fontsize=\footnotesize]{xml}{files/config.xml}
787 \caption{Configuration file template (XML format) for `SlideShow.swf'}\label{SlideShowXML}
788 \end{figure}
789
790 \begin{figure}[bp]
791 \savebox{\keyshift}{\keys{\shift}}%
792 \savebox{\spacebar}{\keys{\unexpanded{\makebox[2\width][c]{Space}}}}%
793 \centering
794 \begin{Verbatim}
795 \includemedia[
796 width=\linewidth,height=\linewidth,
797 activate=pageopen,
798 addresource=files/config.xml, %embedded configuration
799 addresource=files/cubeposter.png, %embedded image file
800 flashvars={xml=files/config.xml},
801 passcontext %show the player's context menu
802 ]{}{SlideShow.swf}
803 \end{Verbatim}
804 \vspace{1ex}
805 \makebox[\linewidth]{\hfill%
806 \includemedia[
807 % width=0.8\linewidth,height=0.6\linewidth,
808 width=\linewidth,height=\linewidth,
809 activate=pageopen,
810 addresource=files/config.xml, %embedded configuration
811 addresource=files/cubeposter.png, %embedded image file
812 flashvars={xml=files/config.xml},
813 passcontext %show the player's context menu
814 ]{}{SlideShow.swf}
815 \hfill}
816 \caption{Slide-show example with one embedded and several remote image files, one of which is a live image. Images 2 and 3 are examples of remote images with variable resolution; the best fitting image resolution is requested from the server depending on the current display size. The listing in Fig.~\ref{SlideShowXML} is used as content of file \Acrobatmenu{ShowHideFileAttachment}{`config.xml'}. Manually cycle forwards through the images by mouse-click or backwards by \usebox{\keyshift}+mouse-click. Play/pause auto-cycling through the slide-show by hitting \usebox{\spacebar}. Also, the context (right-click) menu of the player can be used.}\label{slideshowex}
817 \end{figure}
818
819 \begin{figure}[bp]
820 \centering
821 \begin{Verbatim}
822 \includemedia[
823 width=0.6\linewidth,height=0.3375\linewidth, % 16:9
824 activate=pageopen,
825 flashvars={
826 src=rtmp://streaming.music.indiana.edu:1935/onDemand/mp4:media/%
827 20090327_VarRussianTheme-h264-480.m4v
828 &scaleMode=stretch
829 }
830 ]{}{StrobeMediaPlayback.swf}
831 \end{Verbatim}
832 \vspace{1ex}
833 \makebox[\linewidth]{\hfill\includemedia[
834 width=0.6\linewidth,height=0.3375\linewidth,
835 activate=pageopen,
836 flashvars={
837 src=rtmp://streaming.music.indiana.edu:1935/onDemand/mp4:media/20090327_VarRussianTheme-h264-480.m4v
838 &scaleMode=stretch
839 }
840 ]{}{StrobeMediaPlayback.swf}\hfill}
841 \caption{Example of video streamed from an RTMP server. This example uses media player `StrobeMediaPlayBack.swf', physically embedded in the PDF.}\label{videob}
842 \end{figure}
843
844 \begin{figure}[bp]
845 %\flushright
846 {\small%
847 \begin{Verbatim}
848 \includemedia[
849 addresource=bird.mp3,
850 flashvars={
851 source=bird.mp3
852 &autoPlay=true
853 },
854 transparent,
855 passcontext %show APlayer's right-click menu
856 ]{\color{blue}\framebox[0.4\linewidth][c]{Singing bird}}{APlayer.swf}
857 \end{Verbatim}
858 }
859 \makebox[\linewidth]{(a)\hfill\includemedia[
860 addresource=bird.mp3,
861 flashvars={
862 source=bird.mp3
863 &autoPlay=true
864 },
865 transparent,
866 passcontext %show APlayer's right-click menu
867 ]{\color{blue}\framebox[0.5\linewidth][c]{Singing bird}}{APlayer.swf}
868 \hfill}
869 \vskip 4ex{\small\begin{Verbatim}
870 \includemedia[
871 flashvars={
872 source=http://mp3.live.tv-radio.com/franceculture%
873 /all/franceculturehautdebit.mp3
874 &autoPlay=true
875 },
876 transparent,
877 passcontext %show APlayer's right-click menu
878 ]{\color{blue}\fbox{Listen live to Radio France Culture}}{%
879 http://mirrors.ibiblio.org/pub/mirrors/CTAN/macros/latex/%
880 contrib/media9/players/APlayer.swf%
881 }
882 \end{Verbatim}
883 }
884 \makebox[\linewidth]{(b)\hfill\includemedia[
885 flashvars={
886 source=http://mp3.live.tv-radio.com/franceculture/all/franceculturehautdebit.mp3
887 &autoPlay=true
888 },
889 transparent,
890 passcontext %show APlayer's right-click menu
891 ]{\color{blue}\fbox{Listen live to Radio France Culture}}{%
892 %APlayer.swf%
893 %http://mirror.ctan.org/macros/latex/contrib/media9/players/APlayer.swf%
894 http://mirrors.ibiblio.org/pub/mirrors/CTAN/macros/latex/contrib/media9/players/APlayer.swf%
895 }\hfill}
896 \vskip 4ex
897 {\small%
898 \begin{Verbatim}
899 \includemedia[
900 label=song49,
901 flashvars={source=http://www.openbsd.org/songs/song49.mp3},
902 transparent,
903 passcontext %show VPlayer's right-click menu
904 ]{\color{blue}\fbox{Listen to OpenBSD 4.9 release song}}{APlayer.swf}\\
905 \mediabutton[
906 mediacommand=song49:play[(5.5)],
907 mediacommand=song49:pause[(37)]
908 ]{\fbox{First verse}}
909 \mediabutton[
910 mediacommand=song49:play[(39)],
911 mediacommand=song49:pause[(49)]
912 ]{\fbox{The Answer}}
913 \mediabutton[
914 mediacommand=song49:play[(206.5)],
915 mediacommand=song49:pause[(221)]
916 ]{\fbox{Harmonica solo}}
917 \end{Verbatim}
918 }
919 \makebox[\linewidth]{\rule{0pt}{1.5\baselineskip}\hfill\includemedia[
920 label=song49,
921 flashvars={
922 source=http://www.openbsd.org/songs/song49.mp3
923 },
924 transparent,
925 passcontext %show VPlayer's right-click menu
926 ]{\color{blue}\fbox{Listen to OpenBSD 4.9 release song}}{APlayer.swf}\hfill}\\
927 \makebox[\linewidth]{\makebox[0pt][l]{(c)}\hfill%
928 \mediabutton[
929 mediacommand=song49:play[(5.5)],
930 mediacommand=song49:pause[(37)]
931 ]{\fbox{First verse}}
932 \mediabutton[
933 mediacommand=song49:play[(39)],
934 mediacommand=song49:pause[(49)]
935 ]{\fbox{The Answer}}
936 \mediabutton[
937 mediacommand=song49:play[(206.5)],
938 mediacommand=song49:pause[(221)]
939 ]{\fbox{Harmonica solo}}%
940 \hfill}
941 \caption{Example of (a) embedded sound file, (b) streamed audio and (c) progressively downloaded MP3. ID3 tags `title', `artist' and `album' are displayed if contained in the MP3 stream or file. In (b), the sound player, APlayer.swf, is loaded from a CTAN mirror upon activation.}\label{radio}
942 \end{figure}
943
944 \begin{figure}[bp]
945 \centering
946 \begin{Verbatim}
947 \includemedia[
948 %activate=onclick, % default
949 addresource=cube.mp4,
950 flashvars={
951 source=cube.mp4
952 &autoPlay=true % start playing on activation
953 &loop=true
954 },
955 passcontext %show player's right-click menu
956 ]{\includegraphics[height=0.45\linewidth]{cubeposter}}{VPlayer9.swf}
957 \end{Verbatim}
958 \vspace{1ex}
959 \hfill\includemedia[
960 activate=onclick, %default
961 addresource=cube.mp4,
962 flashvars={
963 source=cube.mp4
964 &autoPlay=true %start playing on activation
965 &loop=true
966 },
967 passcontext %show player's right-click menu
968 ]{\includegraphics[height=0.45\linewidth]{cubeposter}}{VPlayer9.swf}\hfill
969 \vspace{2ex}
970 \begin{Verbatim}
971 \includemedia[
972 addresource=bird.mp3,
973 flashvars={
974 source=bird.mp3
975 &autoPlay=true
976 },
977 transparent,
978 passcontext %show player's right-click menu
979 ]{\color{blue}\framebox[0.4\linewidth][c]{Singing bird}}{APlayer9.swf}
980 \end{Verbatim}
981 \vspace{1ex}
982 \hfill\includemedia[
983 addresource=bird.mp3,
984 flashvars={
985 source=bird.mp3
986 &autoPlay=true
987 },
988 transparent,
989 passcontext %show player's right-click menu
990 ]{\color{blue}\framebox[0.5\linewidth][c]{Singing bird}}{APlayer9.swf}\hfill
991 \vspace{2ex}
992 \caption{Video and sound examples that should run in Adobe Reader for Linux up to version \href{ftp://ftp.adobe.com/pub/adobe/reader/unix/9.x/9.4.1/}{9.4.1}. Here, players `VPlayer9.swf' and `APlayer9.swf' are used. Both are compatible with Adobe Flash Player 9 plugin that is bundled with the Reader. Also, the video player needs to be activated by mouse click (which is the default). We provide a poster image that is shown in the inactive state.}\label{ar941ex}
993 \end{figure}
994
995 \clearpage
996 \section[Embedding 3D objects (with examples)]{Embedding 3D objects}
997 \subsection{Introduction}\label{sec:3Dintro}
998 Adobe Acrobat/Reader 7 was the first version to allow for embedding 3-di\-men\-sion\-al graphic objects, such as CAD models or 3D scientific data, that can be manipulated interactively by the user. U3D was the first supported format and was mainly developed by Right Hemisphere and Adobe. U3D had some deficiencies and was later replaced by the PRC format after Adobe purchased the original developer, the French company `Trade and Technology France'. U3D is still supported, but PRC is preferred as it allows for exact representation of curved surfaces and better compression. Both, U3D and PRC specifications are public~\cite{u3d,prc}.
999
1000 Currently, two open-source software packages are known to export into the PRC file format. The first one is Asymptote~\cite{asy}, which is a descriptive 2D and 3D vector graphics language and interpreter and which uses \TeX{} to typeset labels and equations. It allows for high quality mathematical figures and technical drawings. An impressive gallery of examples can be found on its Web site. The second one is MathGL~\cite{mathgl}, a library for scientific data visualization. It provides interfaces to a number of programming and scripting languages as well as an interpreter for its own command language `MGL'.
1001
1002 MeshLab~\cite{meshlab} is an open-source conversion and processing software for 3D mesh data which can import from and export to a number of file formats. Its U3D export filter is based on the open-source `Universal 3D Sample Software'~\cite{u3dlib}.
1003
1004 There are a few options to \verb+\includemedia+ which define how the 3D object is positioned within the view port of a virtual camera, or conversely, how the virtual camera is positioned and oriented within a coordinate system, called `The World', which bears the 3D object at a fixed position. Fig.~\ref{3dscene} should help to grasp the scenery: The virtual camera is orbiting at a distance of $ROO$ (option `\verb+3Droo+') around the centre of orbit, specified by the position vector $\overrightarrow{COO}$ (option `\verb+3Dcoo+'); $\sphericalangle AAC$ (option `\verb+3Daac+') is the camera's aperture angle. The direction vector $\overrightarrow{C2C}$ (option `\verb+3Dc2c+') is needed to specify the initial camera position. The camera may be given an initial roll angle (option `\verb+3Droll+') around its optical axis $(-1)\cdot\overrightarrow{C2C}$.
1005 \begin{figure}[ht]
1006 \resizebox{\linewidth}{!}{\input{files/3dsystem}}
1007 \caption{Camera and 3D object in the World System $XYZ$; centre of orbit position vector \usebox{\COO}, centre of orbit to camera direction vector \usebox{\CtoC}, radius of orbit $ROO$, aperture angle of camera $\sphericalangle AAC$.}\label{3dscene}
1008 \end{figure}
1009 Fig.~\ref{3dscene} shows the camera parameters for the perspective view mode. Alternatively, the orthographic view mode may be chosen. In orthographic view, the 3D object is parallelly projected onto the virtual camera chip. Before reaching the camera chip, the projected image must be scaled in order to fit onto the chip. Orthographic view can be enabled using the `\verb+3Dortho+' option which takes the scaling factor as its argument.
1010
1011 Above options define the default view, i.\,e. the view that is shown initially after activating the 3D object in the Reader. Of course, once activated, the camera position can be changed using the mouse and one can change forth and back between perspective and orthographic viewing modes using the 3D tool bar.
1012
1013 By default, the virtual camera sits at the origin $(0,0,0)$ of the World, looking in the positive $Y$ direction, i.\,e. default settings of \verb+3Droo=0+, \verb+3Dcoo=0 0 0+ and \verb+3Dc2c=0 -1 0+ are assumed. (Note that $\overrightarrow{C2C}$ is the opposite of the optical axis vector.) Thus, in order to get a `front view' of the 3D object it is sufficient to set the radius of orbit, i.\,e. the distance between camera and object appropriately. Sometimes you may want to adjust the orbital centre, i.\,e. the target of the camera as well, in particular, if the object is irregularly shaped or if it is not centred around the World origin. Fortunately, it is possible to let the values of the corresponding options be determined automatically. Choosing option `\verb+3Dmenu+' adds `\emph{\sffamily Generate Default View}' to the context menu of the activated 3D scene. Selecting this entry calculates and outputs optimal camera settings which can be inserted into the option list of \verb+\includemedia+.
1014
1015 Additional resource files that are needed to render the 3D scene can be embedded using the `\verb+addresource+' option. Typical resources are bitmaps and Flash files (even animated and interactive ones), to be used as materials or scene backgrounds, as well as additional 3D objects in the U3D or PRC file format. The allowed file formats of \emph{bitmapped} image files depend on the \LaTeX workflow. \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+/Distiller accepts PS and EPS files; pdf\LaTeX{} accepts PNG, JPEG and JBIG2; \pXepLaTeX{} $\rightarrow$ \verb+(x)dvipdfmx+ accepts PNG and JPEG. 3D JavaScript is necessary to load these resources upon activation. 3D JavaScript files are attached using the `\verb+add3Djscript+' option.
1016
1017 Below, several examples of embedded 3D files are shown. The first one, Fig.~\ref{asyex} is a PRC file generated with Asymptote. Note the text labels always facing the camera thanks to the attached 3D JavaScript file `asylabels.js'. The second example, Fig.~\ref{u3dex}, demonstrates the use of a views file which defines additional named views of the 3D object. Moreover, the possibilities of the extended 3D context menu can be evaluated. They were enabled by adding the `\verb+3Dmenu+' option to \verb+\includemedia+. All part and scene rendering attributes that can be changed via the `\emph{\sffamily Part Options}' and `\emph{\sffamily Viewing Options}' menu entries, as well as a cross section to be added with the `\emph{\sffamily Cross Section}' menu entry can be saved into a new view (`\emph{\sffamily Get Current View}'). Position, orientation and scaling of individual parts and of the cross section can be changed using the keyboard (keys \keys{\arrowkeyleft}, \keys{\arrowkeyright}, \keys{\arrowkeyup}, \keys{\arrowkeydown}, \keys{X}, \keys{\shift+X}, \keys{Y}, \keys{\shift+Y}, \keys{Z}, \keys{\shift+Z}, \keys{S}, \keys{\shift+S}). The third example, Fig.~\ref{u3dex2}, shows an animated 3D object. The animation itself and the functions called by pressing the controls are defined in a 3D JavaScript file attached to the model.
1018
1019 \begin{figure}[bp]
1020 \centering
1021 \begin{Verbatim}
1022 \includemedia[
1023 width=0.8\linewidth,height=0.8\linewidth,
1024 add3Djscript=asylabels.js, %upright text labels
1025 add3Djscript=3Dspintool.js, %let scene rotate about z-axis
1026 % 3Dcoo, 3Droo values found with `Generate Default View' from
1027 % context menu
1028 3Dmenu,
1029 3Dc2c=4 2 3,
1030 3Dcoo=4.413303375244141 2.195653200149536 -0.000011444091796875,
1031 3Droo=429.49035778293376,
1032 ]{\includegraphics{epixposter}}{epix.prc}
1033 \end{Verbatim}
1034 \vspace{1ex}
1035 \includemedia[
1036 width=0.8\linewidth,height=0.8\linewidth,
1037 add3Djscript=asylabels.js, %upright text labels
1038 add3Djscript=3Dspintool.js, %let scene rotate about z-axis
1039 % 3Dcoo, 3Droo values found with `Generate Default View' from
1040 % context menu
1041 3Dmenu,
1042 3Dc2c=4 2 3,
1043 3Dcoo=4.413303375244141 2.195653200149536 -0.000011444091796875,
1044 3Droo=429.49035778293376,
1045 ]{\includegraphics{epixposter}}{epix.prc}
1046 \caption{Embedded PRC file produced with Asymptote, making use of convenience 3D JavaScripts `asylabels.js' and `3Dspintool.js' mentioned
1047 {\leavevmode\pdfstartlink attr{/Border[0 0 1]/C[0 0 1]/H/I}user{/Subtype/Link/A<</D(3dscripts)/S/GoTo>>}above\pdfendlink}.}\label{asyex}
1048 \end{figure}
1049
1050 \begin{figure}[bp]
1051 \begin{Verbatim}[fontsize=\footnotesize]
1052 \includemedia[
1053 label=dice,
1054 width=0.5\linewidth,height=0.5\linewidth,
1055 activate=pageopen,
1056 3Dtoolbar, 3Dmenu,
1057 3Dviews=dice.vws,
1058 ]{}{dice.u3d}
1059
1060 \mediabutton[3Dgotoview=dice:N]{\fbox{Next view}}
1061 \mediabutton[3Dgotoview=dice:(Back)]{\fbox{View `Back'}}
1062 \mediabutton[3Dgotoview=dice:5]{\fbox{6th view in the list}}
1063 \end{Verbatim}
1064 \vspace{1ex}
1065 Contents of `dice.vws':
1066 \begin{Verbatim}[fontsize=\footnotesize]
1067 VIEW=Front
1068 ROO=27
1069 END
1070 VIEW=Back
1071 ROO=27
1072 C2C=0 1 0
1073 END
1074 VIEW=Left
1075 ROO=27
1076 C2C=-1 0 0
1077 END
1078 VIEW=Right
1079 ROO=27
1080 C2C=1 0 0
1081 END
1082 VIEW=Top
1083 ROO=27
1084 C2C=0 0 1
1085 END
1086 VIEW=Bottom
1087 ROO=27
1088 C2C=0 0 -1
1089 END
1090 VIEW=Fish Eye at Centre
1091 AAC=130
1092 END
1093 \end{Verbatim}
1094 \centering
1095 \raisebox{-0.7\height}{\includemedia[
1096 label=dice,
1097 width=0.5\linewidth,height=0.5\linewidth,
1098 activate=pageopen,
1099 3Dtoolbar,
1100 3Dviews=dice.vws,
1101 3Dmenu,
1102 ]{}{dice.u3d}}\quad\parbox[t]{0.4\linewidth}{%
1103 \mediabutton[3Dgotoview=dice:N]{\fbox{Next view}}\\
1104 \mediabutton[3Dgotoview=dice:(Back)]{\fbox{View `Back'}}\\
1105 \mediabutton[3Dgotoview=dice:5]{\fbox{6th view in the list}}}
1106 \caption{Embedded U3D file, based on a VRML model by Peter Whitehouse, \url{http://www.wonko.info/vrml/index.htm}; conversion to U3D was done using DeepExploration\textsuperscript{\scriptsize\textregistered}\cite{dexp}. The file `{\tt dice.vws}' provides predefined views. Buttons are created with {\tt\string\mediabutton} using the `{\tt 3Dgotoview}' option.}\label{u3dex}
1107 \end{figure}
1108
1109 \begin{figure}
1110 \begin{Verbatim}
1111 \includemedia[
1112 label=malte,
1113 width=0.5\linewidth,height=0.5\linewidth,
1114 activate=pageopen,
1115 3Dmenu,
1116 3Dc2c=1 1 1,
1117 3Dcoo=-0.001042630523443222 1.4577869224116568e-19 0.028235001489520073,
1118 3Droo=0.2604540212188131,
1119 add3Djscript=malte.js
1120 ]{}{malte.u3d}
1121
1122 \mediabutton[
1123 jsaction=malte:{annotRM['malte'].context3D.cntrClockWise();}
1124 ]{\includegraphics[height=1.44em]{boutona}}
1125 \mediabutton[
1126 jsaction=malte:{annotRM['malte'].context3D.pause();}
1127 ]{\includegraphics[height=1.44em]{boutonb}}
1128 \mediabutton[
1129 jsaction=malte:{annotRM['malte'].context3D.clockWise();}
1130 ]{\includegraphics[height=1.44em]{boutonc}}
1131 \hspace{1em}
1132 \mediabutton[
1133 jsaction=malte:{annotRM['malte'].context3D.scaleSpeed(1/1.1);}
1134 ]{\includegraphics[height=1.44em]{boutond}}
1135 \mediabutton[
1136 jsaction=malte:{annotRM['malte'].context3D.origSpeed();}
1137 ]{\includegraphics[height=1.44em]{boutone}}
1138 \mediabutton[
1139 jsaction=malte:{annotRM['malte'].context3D.scaleSpeed(1.1);}
1140 ]{\includegraphics[height=1.44em]{boutonf}}
1141 \end{Verbatim}
1142 \centering
1143 \includemedia[
1144 label=malte,
1145 width=0.5\linewidth,height=0.5\linewidth,
1146 activate=pageopen,
1147 3Dmenu,
1148 3Dc2c=1 1 1,
1149 3Dcoo=-0.001042630523443222 1.4577869224116568e-19 0.028235001489520073,
1150 3Droo=0.2604540212188131,
1151 add3Djscript=malte.js
1152 ]{}{malte.u3d}
1153
1154 \mediabutton[jsaction=malte:{annotRM['malte'].context3D.cntrClockWise();}]{\includegraphics[height=1.44em]{boutona}}
1155 \mediabutton[jsaction=malte:{annotRM['malte'].context3D.pause();}]{\includegraphics[height=1.44em]{boutonb}}
1156 \mediabutton[jsaction=malte:{annotRM['malte'].context3D.clockWise();}]{\includegraphics[height=1.44em]{boutonc}}
1157 \hspace{1em}
1158 \mediabutton[jsaction=malte:{annotRM['malte'].context3D.scaleSpeed(1/1.1);}]{\includegraphics[height=1.44em]{boutond}}
1159 \mediabutton[jsaction=malte:{annotRM['malte'].context3D.origSpeed();}]{\includegraphics[height=1.44em]{boutone}}
1160 \mediabutton[jsaction=malte:{annotRM['malte'].context3D.scaleSpeed(1.1);}]{\includegraphics[height=1.44em]{boutonf}}
1161 % \mediabutton[
1162 % mediacommand=malte:cntrClockWise
1163 % ]{\includegraphics[height=1.44em]{boutona}}
1164 % \mediabutton[
1165 % mediacommand=malte:pause
1166 % ]{\includegraphics[height=1.44em]{boutonb}}
1167 % \mediabutton[
1168 % mediacommand=malte:clockWise
1169 % ]{\includegraphics[height=1.44em]{boutonc}}
1170 % \hspace{1em}
1171 % \mediabutton[
1172 % mediacommand=malte:scaleSpeed [0.91]
1173 % ]{\includegraphics[height=1.44em]{boutond}}
1174 % \mediabutton[
1175 % mediacommand=malte:origSpeed
1176 % ]{\includegraphics[height=1.44em]{boutone}}
1177 % \mediabutton[
1178 % mediacommand=malte:scaleSpeed [1.1]
1179 % ]{\includegraphics[height=1.44em]{boutonf}}
1180 \caption{Animated U3D example of a Maltese drive contributed by Jean-Luc Chesnot. The animation and the functions called in the JavaScript actions of the media buttons are defined in the JavaScript file `{\tt malte.js}'.}\label{u3dex2}
1181 \end{figure}
1182 \clearpage
1183 \subsection{3D quick-start guide}\label{sec:3Dtut}
1184 \begin{enumerate}
1185 \item Insert the 3D object with default camera settings and with extended context menu enabled (option `\verb+3Dmenu+'):
1186
1187 \begin{Verbatim}
1188 \includemedia[
1189 width=0.5\linewidth,height=0.5\linewidth,
1190 activate=pageopen,
1191 3Dmenu
1192 ]{}{myfile.u3d}
1193 \end{Verbatim}
1194
1195 \item Compile the document.
1196 \item Open the PDF document in Adobe Reader and go to the page containing the 3D object. Select `\emph{\sffamily Generate Default View}' from the 3D context menu (right mouse click) and wait for the JavaScript console to pop up. Optionally, drag the object with the mouse to change the viewpoint of the camera and select `\emph{\sffamily Generate Default View}' again. This will re-adjust the distance between camera and target to fit all visible parts tightly into the viewport. The options printed into the console are updated accordingly.
1197 \item Copy the camera settings ({\tt 3Droo=...}, {\tt 3Dcoo=...}, etc.) from the console into the option list of {\tt \string\include\-media}.
1198 \item Compile the document again.
1199 \xdef\lastcount{\theenumi}
1200 \end{enumerate}
1201
1202 \emph{Optional steps} (option `{\tt 3Dmenu}' required):
1203
1204 \begin{enumerate}
1205 \setcounter{enumi}{\lastcount}
1206 \item Additional, named views; cross sections; rescaled, repositioned parts:
1207 \begin{itemize}
1208 \item[a)] Open a text file, e.\,g. `myviews.vws', to be populated with additional views of the 3D object.
1209 \item[b)] Manipulate the 3D object using the mouse (camera position) and via 3D context menu items `\emph{\sffamily Part Options}' and `\emph{\sffamily Viewing Options}' (visibility, rendering attributes, background etc.); the camera target can be moved into the centre of a single part via `\emph{\sffamily Part Options}'$\rightarrow$`\emph{\sffamily Zoom to Part}'.
1210 \item[c)] Add a cross section plane (select `\emph{\sffamily Cross Section}' from the 3D context menu), adjust its position using the keyboard; keyboard keys are given \hyperlink{3dmenu}{here}.
1211 \item[d)] Adjust scaling and position of individual parts using the keyboard; keyboard keys are given \hyperlink{3dmenu}{here}.
1212 \item[e)] Re-adjust the camera distance using either `\emph{\sffamily Generate Default View}' or `\emph{\sffamily Part Options}'$\rightarrow$`\emph{\sffamily Fit Visible}'.
1213 \item[f)] When you are done, select `\emph{\sffamily Get Current View}' to get the {\tt VIEW} section, readily formatted for insertion into the views file. Repeat steps (a)--(f) to get any number of views you want to define. The views file can be edited manually to give meaningful names to the views (change the value of the {\tt VIEW} key), or to further tweak camera settings, opacity, part options etc.
1214 \item[g)] Attach the views file with option `{\tt 3Dviews}':
1215 \begin{Verbatim}
1216 \includemedia[
1217 width=0.5\linewidth,height=0.5\linewidth,
1218 activate=pageopen,
1219 3Dviews=myviews.vws,
1220 3Dmenu
1221 ]{}{myfile.u3d}
1222 \end{Verbatim}
1223 If you are satisfied with the predefined views in the views file, the default view first specified through the options of {\tt\string\includemedia} can be deleted. The first view in the views file becomes the default view then.
1224 \end{itemize}
1225 \item Associate any number of 3D JavaScript files with the 3D object:
1226 \begin{Verbatim}
1227 \includemedia[
1228 width=0.5\linewidth,height=0.5\linewidth,
1229 activate=pageopen,
1230 add3Djscript=somescript.js,
1231 add3Djscript=otherscript.js,
1232 3Dviews=myviews.vws,
1233 3Dmenu
1234 ]{}{myfile.u3d}
1235 \end{Verbatim}
1236 A few 3D JavaScript files ready to be used are already installed along with `media9.sty', see \hyperlink{3dscripts}{above}.
1237 \end{enumerate}
1238
1239 \section{Caveats}\label{bugs}
1240 \begin{enumerate}
1241 \item Large media files may cause \TeX{} to interrupt with error
1242 \begin{verbatim}
1243 ! TeX capacity exceeded, sorry [main memory size=3000000].
1244 \end{verbatim}
1245 when using \verb+latex+ in \verb+dvips+ mode. While writing the DVI file, media files in the current page that are about to be embedded are kept in \TeX's memory until shipping out of the readily typeset page. In the case of large or many files, this may be more than \TeX{} can cope with by default.
1246
1247 There are two options to handle such situations:
1248
1249 The first one is to increase \TeX's main memory. You may follow the steps in the \href{http://mirror.ctan.org/macros/latex/contrib/animate/animate.pdf\#dest:mem}{Bugs} section of the `animate' package documentation. In \TeX{}Live-2012, the maximum value that can be set is \verb+main_memory = 12435455+.
1250
1251 If increasing \TeX's main memory does not help, use the package option `\verb+bigfiles+' with media9. It defers file embedding from the DVI producing to the PS producing step.
1252
1253 \item In right-to-left typesetting context (RTL) using the (pdf)\LaTeX{} or \XeLaTeX{} engines, the \verb+<poster text>+ argument of \verb+\includemedia+ and the text arguments for button faces of the \verb+\mediabutton+ command should be enclosed in pairs of \verb+\beginR+ and \verb+\endR+.
1254 \end{enumerate}
1255
1256 \section{Acknowledgements}
1257 This package was written using the new \LaTeX3 syntax which was a lot of fun. Many thanks to the \LaTeX3 team!
1258
1259 \begin{thebibliography}{9}
1260 \bibitem{strobe} Adobe Systems Inc.: \emph{Strobe Media Playback}, 2010, available at \url{http://osmf.org/strobe_mediaplayback.html}
1261
1262 \bibitem{supplement} Adobe Systems Inc.: \emph{Adobe Supplement to ISO 32000, BaseVersion 1.7, ExtensionLevel 3}, 2008, available at \url{https://www.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/adobe_supplement_iso32000.pdf}
1263
1264 \bibitem{jscript3D} Adobe Systems Inc.: \emph{JavaScript for Acrobat 3D Annotations API Ref\-er\-ence}, available at \url{https://help.adobe.com/en_US/acrobat/acrobat_dc_sdk/2015/HTMLHelp/Acro12_MasterBook/JS_3D_Intro/JS_3D_Intro.htm}
1265
1266 \bibitem{jscript} Adobe Systems Inc.: \emph{JavaScript for Acrobat API Reference}, available at \url{https://help.adobe.com/en_US/acrobat/acrobat_dc_sdk/2015/HTMLHelp/Acro12_MasterBook/JS_API_AcroJSPreface/JS_API_AcroJSPreface.htm}
1267
1268 \bibitem{flex} The Apache Software Foundation: \emph{Apache Flex SDK}, available at \url{http://flex.apache.org}
1269
1270 \bibitem{u3d} ECMA International: \emph{Universal 3D File Format (ECMA-363), 4th Edition}, 2007, available at \url{http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-363\%204th\%20Edition.pdf}
1271
1272 \bibitem{prc} Adobe Systems Inc.: \emph{PRC Format Specification}, available at \url{https://web.archive.org/web/20081202034541/http://livedocs.adobe.com/acrobat_sdk/9/Acrobat9_HTMLHelp/API_References/PRCReference/PRC_Format_Specification/index.html}
1273
1274 \bibitem{asy} A. Hammerlindl, J. Bowman and T. Prince: \emph{Asymptote: The Vector Graphics Language}, available at \url{http://asymptote.sourceforge.net}
1275
1276 \bibitem{mathgl} A. A. Balakin: \emph{MathGL - library for scientific graphics}, available at \url{http://mathgl.sourceforge.net}
1277
1278 \bibitem{u3dlib} T. O'Rourke, T. Strelchun: \emph{Universal 3D Sample Software}, available at \url{http://sourceforge.net/projects/u3d}
1279
1280 \bibitem{meshlab} P. Cignoni \emph{et al.}: \emph{MeshLab}, available at \url{http://meshlab.sourceforge.net}
1281
1282 \bibitem{dexp} RightHemisphere Inc.: \emph{DeepExploration}, \url{http://www.righthemisphere.com/products/dexp/}
1283 % \bibitem{swftools} R. B\"ohme, M. Kramm: \emph{Swftools}, available at \url{http://www.swftools.org}
1284 \end{thebibliography}
1285
1286 \end{document}