http://impressive.sourceforge.net/
Version: 0.11.0 – 0.11.1
Author: Martin J. Fiedler
Last updated: 2014-12-21
Impressive is a simple presentation program that displays slideshows of image files (JPEG, PNG, TIFF and BMP) or PDF documents. Rendering is done via OpenGL, which allows for some “eye candy” effects.
A somewhat-modern GPU (graphics processing unit) supporting OpenGL 2.0 or OpenGL ES 2.0 and appropriate drivers is required to run Impressive.
There are three basic ways to get an Impressive installation on your computer. The following section will guide you through each of these methods.
For Windows systems, a ZIP file with a pre-built version of Impressive and all required external tools can be downloaded from the web site. There is no real installation procedure – the ZIP file can be extracted into any folder. One of the extracted file is called impressive.exe. PDF files or directories containing images can simply dropped onto this file in Explorer to run a presentation with default settings.
A more comfortable method is installing Impressive in the »Send To« menu that's part of each file's context menu. This is done by opening the location shell:sendto in Explorer and creating a shortcut to impressive.exe there. After that, a presentation can be started by right-clicking a PDF file and selecting »Send To → Impressive«.
Most GNU/Linux distributions offer Impressive as part of their standard package repositories, among them Debian, Ubuntu, Fedora, OpenSUSE and Arch Linux. The package is typically called impressive and will install all necessary dependencies.
On Mac OS X, there is a py-impressive package in the MacPorts repositories, but at the time of writing, it's extremely outdated and thus not recommended.
In general, the easy method of installing the Windows ZIP or distribution package is simple and convenient, but it has caveats: Releases of Impressive only happen in long and irregular intervals, and the package maintainers may be a few versions behind. Recent features and bugfixes will thus not be available.
Another way to get Impressive is downloading the platform-independent source code version. The most important file in this archive is impressive.py, which contains all the code of Impressive and can be run like any executable on Unix-like systems. However, the following external libraries and utilities have to be installed as well for Impressive to work:
On Unix-like systems, these dependencies are typically available in the major distributions' package repositories and can be installed easily with the package managers, e.g.:
aptitude install python-pygame python-imaging pdftk mupdf-tools xdg-utils mplayeryum -i pygame python-pillow pdftk mupdf xdg-utils mplayerpacman -S python2-pygame python2-pillow pdftk mupdf xdg-utils mplayerport install py27-game py27-pil pdftk mupdf xdg-utils mplayerThe source code of Impressive is maintained in a Subversion (SVN) repository. For users that want the newest version or want to help with debugging or developing Impressive, it is recommended to check out this repository:
svn co http://svn.emphy.de/impressive/trunk/impressive
Regarding external dependencies, the section above applies as well; in addition, Subversion (whose package is usually called svn or subversion) is obviously required too.
After checking out the sources, the impressive.py program will still be missing. Instead, the main program is called impressive_dev.py and is functionally equivalent; it pulls the actual source files from the src subdirectory and runs them. To get a real stand-alone impressive.py file for redistribution (or for putting it e.g. into /usr/local so it can be run from everywhere), it needs to be generated using either make (if GNU Make is installed) or python compile.py.
When used from the command line (some terminal and shell in Unix, cmd.exe on Windows), Impressive accepts a range of command-line options in GNU getopt syntax.
The following options are available (in alphabetical order):
-a <seconds> or --auto <seconds>-w option (described below), this can be used to create automatic slideshows.-A <X>:<Y> or --aspect <X>:<Y>-b or --noback--cache none, see below).-B <ms> or --boxfade <ms>-c <mode> or --cache <mode>nonememorycompressed or zmemory mode, but on pages with uniform backgrounds, this will easily reduce the required amount of RAM by a factor of 20.diskmemory, but uses a temporary file rather than memory for storage. This is the default.persistent.cache file name extension instead of .info. This method is a little bit slower than disk mode, but the time span until the overview page is fully populated will be significantly decreased if Impressive is ran again with the same input files and options.--cache persistent, -c persist and even -cp are all synonyms.-C <filename>[:<X>,<Y>] or --cursor <filename>[:<X>,<Y>]-« (dash) or »default«, both of which select a built-in cursor image. On platforms that do not support a hardware cursor, this default cursor will also be used as a default if this option is not used.--cursor mycursor.png:2,4.--clock-M option.--control-help-e/--bind or -E/--controls options precede this option). After that, Impressive will exit; no presentation will be started.-d <time> or --duration <time>1:23 (1 minute and 23 seconds), 4:56h (4 hours and 56 minutes), 3m45s (3 minutes and 45 seconds), 5m (5 minutes) or 1:23:45 (1 hour, 23 minutes and 45 seconds).-D <ms> or --mousedelay <ms>--darkness <percentage>-e <bindings> or --bind <bindings>-E <filename> or --controls <filename>--evtest-f--fullscreen, --windowed and --fake-fullscreen).--fullscreen-f option for details.--fake-fullscreen-f option for details.-F <file> or --font <file>/usr/share/fonts, /usr/local/share/fonts or /usr/X11R6/lib/X11/fonts/TTF for this purpose (the latter one is useful for Mac OS X systems specifically). If this option is not specified, Verdana.ttf will be used as a default if the operating system is Windows, or any of DejaVuSans.ttf or Vera.ttf (the typical file name of Bitstream Vera Sans) if it's not.-g <width>x<height>[+<posX>+<posY>] or --geometry <width>x<height>[+<posX>+<posY>]xrandrinstalled, the default screen size for fullscreen mode is the current screen resolution; on other platforms, Impressive uses the highest resolution available to the graphics system. If a standard resolution cannot be determined, the default is 1024x768 pixels. This is also the default for windowed mode.-G <gamma>[:<blacklevel>] or --gamma <gamma>[:<blacklevel>]-h or --help-H or --half-screenbeamer class), this makes it possible to have presenter's notes on the second screen.PagePeel) look ugly. Impressive also disables the overview zoom animation in half-screen mode; it can be re-enabled by explicitly setting it to another value with a later command line option (--zoomtime).-i <page> or --initialpage <page>-I <filename> or --script <filename>--invert-k or --auto-progress--auto command-line option). Nothing is done on pages that don't have a timeout.--duration or --page-progress bars: If one of these options is specified as well, the timeout progress bar will be shown on pages with a timeout, and the other progress bar will be shown on pages without one.-l or --listtrans*) left of the class name.-L <spec> or --layout <spec>--min-box-size <pixels>-M or --minutes--noblur--noblur option can be used to enforce the fallback implementation.--noclicks-e/--bind or -E/--controls options have been used, --noclicks might not have the intended effect.--nologo-o <directory> or --output <directory>-g option. This option is useful if the presentation is to be given on on a foreign PC with an old, broken or otherwise problematic Xpdf installation: By generating images of the PDF pages, is is made sure that no rendering bugs will happen on the target system.-O <mode> or --autooverview <mode>pdftk), except those that contain multiple reveal steps.offfirstlast-c option above..-p <start>-<end> or --pages <start>-<end>-P <path> or --gspath <path>gs or gs.exe) or Xpdf's pdftoppm utility must be specified.-q or --page-progress-d option) is also enabled.-Q or --autoquit--wrap is used.-r <n> or --rotate <n>-r 1 or -r 3 if there are problems with PDFs generated by LaTeX on some Xpdf or GhostScript versions.-s or --scale (image input only)-s or --supersample (PDF input only)-S <pixels> or --fontsize <pixels>--spot-radius <pixels>-t <ms> or --transition <trans1[,trans2...]>-l option can be used to get a list of available transitions.-T <ms> or --transtime <ms>--tracking-u <seconds> or --poll <seconds>-v or --verbose-V <pixels> or --overscan <pixels>-w or --wrap-W or --nowheel-e/--bind or -E/--controls options have been used, --noclicks might not have the intended effect.--windowed-f option for details.-x or --fade-X or --shuffle-y or --auto-auto--duration to have Impressive compute a page timeout (as with the --auto option) automatically. This results in a presentation that runs automatically, displaying each slide for the same time, so that the desired total duration will be reached (almost) exactly.-z <factor> or --zoom <factor>-e option is used, the number must be a power of two.-Z <ms> or --zoomtime <ms>--cachefile <filename>Following the options, the input file name(s) must be specified. Recognized file types are PDF, JPEG, PNG, TIFF, BMP and PGM/PPM. If the name of a directory is put on the command line, all recognized image files (no PDF files!) in this directory will be played in alphanumeric order (case-insensitive).
In addition, Impressive can use a text file containing a list of files or directories to show: This text file must contain at most one file name per line; every character after a hash sign (#) is treated as a comment and will be ignored. If such a comment is put on the same line as an image file name, it will be used as the page's title. List file names must be prefixed with an at sign (@) on the command line, e.g. impressive @my_list_file.
Impressive will also expand wild-card characters (* and ?) if this isn't already done by the shell, but apart from that, it will not reorder the arguments. Thus, it will show the documents in the order specified at the command line.
The OSD layout option (-L/--layout) accepts a string with comma-separated key=value pairs. The following keywords are recognized:
alphamargintimetitlepagestatusThe position specifications are composed by one character that indicates whether the text shall be displayed at the top (T) or bottom (B) edge of the screen and one character that indicates whether it shall appear on the left (L), on the right (R) or centered (C).
For example, the default OSD layout equals the following option string:
-L margin=16,alpha=1,time=TR,title=BL,page=BR,status=TL
The following examples illustrate some typical command lines. They assume that Impressive can be run by simply typing »impressive« on the command line. Depending on how Impressive is installed, this has to be substituted with the actual way to run Impressive (e.g. »python ~/impressive/impressive_dev.py« for a fresh SVN checkout). Furthermore, the file »demo.pdf« is used as the document to show here; obviously this has to be replaced by the path to the actual PDF file too.
In the simplest case, Impressive is run directly with the name of the file to show and no further parameters. This will start a full-screen presentation with all settings at their defaults:
impressive demo.pdf
To just quickly check a slide deck, it might make sense to run Impressive in a small window and not full-screen. This can be done with something like
impressive -f -g 800x600 demo.pdf
Impressive can also be used in digital signage scenarios, like displays in shop windows with a permanent slideshow. This can be achieved by having Impressive advance to the next page automatically after a specified time (e.g. 10 seconds) and re-start the presentation from the start after the last slide:
impressive -a 10 -w demo.pdf
On startup, Impressive will display a black screen with the program logo at the center. If caching is enabled, but background rendering is disabled, all pages of the presentation will then be rendered once. A bar in the lower half of the screen displays the progress of this operation. Any key or mouse click (except for those that quit Impressive, typically Q and Esc) skips this process, with the effect that Impressive will render the remaining pages on demand. Please note that the overview page will not be complete until every page has been rendered at least once. In other words, if the precaching process was skipped, placeholders will be displayed for all pages that have not been rendered yet. By default, Impressive will build up the cache in the background while the presentation runs. Thus, the progress bar will not appear and the preparation will only take the amount of time required to render the first two pages of the presentation. After this initialization process, Impressive will switch to the first page directly and without any transition.
The keyboard and mouse controls used by Impressive are configurable (with very few exceptions). The default controls are as follows:
pdftk is installed. Furthermore, xdg-open from the freedesktop.org Portland project is required for URL links on non-Win32 platforms. Please note that the hyperlink feature will not work properly when pages are rotated.--tracking had been specified.radius page property, the --spot-radius command-line option or Impressive's built-in default.darkness page property, the --darkness command-line option or Impressive's built-in default.Any alphanumeric (A-z, 0-9) or function key (F1-F12) that is not bound to a specific action mentioned above or configured by the user (see below) can be used to assign shortcuts to pages that require quick access. If one of the keys is pressed together with Shift, the currently displayed page is associated with this key. To recall the page later, it is sufficient to press the shortcut key again. Shortcuts can be stored permanently with the S key.
As already mentioned in the previous chapter, the keyboard and mouse bindings of Impressive can be widely configured. The only exceptions are the Alt+F4 and Alt+Tab key combinations that will always quit or minimize Impressive, respectively. For everything else, there is a versatile configuration system in place; the controls described in the previous section are merely the defaults.
Impressive's control system works by associating events with actions. An event is a key on the keyboard, a mouse button or a mouse wheel movement. An action is something that is performed by Impressive as a result of an event, like going to the next page, switching to overview mode or quitting the program. The association of an event to an an action is called a binding. Multiple events can be bound to the same action (like the page down and space keys in the default setting, both of which go to the next page); furthermore, multiple actions can be bound to the same event. In fact, bindings do not associate events with single actions at all, but with chains of actions. Only the first action in the chain that matches (i.e. makes sense in) the current context will be executed if the event fires; all other actions will be ignored. If no action matches, no action will be performed and the event will be ignored.
One example of such an action chain is the default binding for the left mouse button, which
Both events and actions have mnemonic names that are used in the command-line options and configuration files used for setting up bindings. Event and actions names are generally case-insensitive, though the canonical notation is lowercase.
If an event or action specified on the command line or in a configuration file is not recognized by Impressive, an error message will be written to the console and the offending event or action will be ignored. Errors in control configuration are thus always non-fatal.
Keyboard events are generally named after the keys they refer to. Consequently, the events a to z and 0 to 9 mean the respective letter and number keys on the main keyboard, f1 to f12 are the function keys and kp0 to kp9 are the number keys on the numerical keypad. All of these are raw scancodes, which has two implications: First, the key names are not internationalized and refer to the US keyboard layout (e.g. the Z key on a German or French keyboard will actually react to the event name y or w); second, modifiers will be ignored as well (e.g. the numerical keypad will always generate the kpX scancodes, even if Num Lock is off).
The mnemonic names for the other keyboard events are as follows (in alphabetic order): ampersand, asterisk, at, backquote, backslash, backspace, break, capslock, caret, clear, comma, down, end, escape, euro, exclaim, greater, hash, help, home, insert, kp_divide, kp_enter, kp_equals, kp_minus, kp_multiply, kp_plus, lalt, last, lctrl, left, leftbracket, leftparen, less, lmeta, lshift, lsuper, menu, minus, mode, numlock, pagedown, pageup, pause, period, plus, power, print, question, quote, quotedbl, ralt, rctrl, return, right, rightbracket, rightparen, rmeta, rshift, rsuper, scrollock, semicolon, slash, space, sysreq, tab, underscore, up. The events prefixed with kp_ refer to keys on the numerical keypad. Other than that, the names should be reasonably descriptive, so they will not be described futher at this point. Also note that not all keyboards and platforms support the full range of keys defined in this list.
Mouse event names are mapped as follows:
lmbmmbrmbwheelupwheeldownThe event names can be prefixed with the three modifiers ctrl+, alt+ and shift+ to make the event valid only if the specified set of modifiers is pressed as well. This works for both keyboard and mouse events. Multiple modifiers can be combined, but the order must match the one mentioned in this paragraph. For example, ctrl+shift+x is a valid event name, while shift+ctrl+x is not.
A simple way to determine the name associated with an event is using Impressive's »Event Test Mode« by invoking impressive --evtest. In this mode, the name of each incoming event will be displayed on the screen (and logged to standard output), which makes it possible to determine event names by experimentation.
The following list describes all actions supported by Impressive, together with the conditions under which they will match. Note that most actions will not match in overview mode and during video playback, unless mentioned otherwise in the description.
box-addbox-clearbox-removefade-less, fade-morefade-resetfade-to-black, fade-to-whitequit action will just leave fade mode and not perform its assigned action.fullscreengamma-decrease, gamma-increasegamma-bl-decrease, gamma-bl-increasegamma-resetgoto-end, goto-end-notransgoto-last, goto-last-notransgoto-next, goto-next-notransgoto-prev, goto-prev-notransgoto-start, goto-start-notranshyperlink, hyperlink-notransoverview-confirmoverview-down, overview-upoverview-enteroverview-exitoverview-next, overview-prevquitsavespotlight-enterspotlight-exitspotlight-grow, spotlight-shrinkspotlight-resettime-resettime-toggle--clock option is used. If this is done at the start of the presentation, before the first page has been left, time tracking mode will be enabled, like the --tracking option would have done.toggle-overviewtoggle-skipgoto-prev and goto-next« flag for the current page.video-pausevideo-seek-backward-10, video-seek-backward-1, video-seek-forward-1, video-seek-forward-10video-stepvideo-stopzoom-enterzoom-exitzoom-panThe arguments of the -e/--bind command-line option have the following basic syntax:
<event> [,<event2>...] <operator> <action> [,<action2>...]
In other words, it is a sequence of event names joined with commas, followed by an operator (see below) and a sequence of action names joined with commas. Multiple such binding statements can be combined into one argument by joining them with a semicolon (;).
The used operator defines in which way the action list shall modify the bindings of the referenced events:
= (equals sign), += (plus sign and equals sign)event=action1,action2 does exactly the same as event=action1; event=action2.:= (colon and equals sign)-= (minus sign and equals sign)escape -= box-clear can be used.Other than bindings, a statement can also contain one of the following special commands:
clearalldefaultsinclude <filename>The syntax for the configuration files used with the -E/--controls option or include statement is exactly the same as for the ad-hoc configuration option, except that individual bindings can be written on individual lines instead of joining them together to a single long line with semicolons. In addition, everything following a hash sign (#) on a line will be ignored as a comment.
One practical example for such a configuration file can be the following: The author of this program uses a cheap presentation remote control device that has four cursor keys, one »enter« key and a slider that switches between keyboard and mouse mode. Mouse mode works as expected, but what it does in keyboard mode is quite peculiar: the up and down keys act like Page-Up and Page-Down keys on a keyboard, the right arrow key sends the letter B to the computer, and the left key toggles between Esc and F5 each time it's pressed. The following configuration file allows basic navigation and access to overview mode with this device:
clearall # don't use the default bindings
lmb = quit # quit Impressive by clicking in mouse mode
# everything else uses keyboard mode:
return = overview-enter, overview-confirm # toggle overview mode
escape, f5 = overview-prev, goto-prev
b = overview-next, goto-next
pageup = overview-up, goto-prev
pagedown = overview-down, goto-next
To get a better idea of how the control configuration system works in practice, it's recommended to study the output of impressive --control-help – this not only gives a concise overview of all events and actions, but also a full dump of Impressive's default bindings that can be used as a starting point for own customizations.
Impressive offers a powerful way to customize individual presentations using so-called info scripts. An info script is a text file having the same name and located in the same directory as the presentation file itself, except for the additional suffix .info. Thus, a presentation file called BrandNewProduct.pdf would have a info script with the name BrandNewProduct.pdf.info. If multiple arguments were specified on the command line, the info script will be called just .info (a dot file, so to speak). If a directory name was specified as the only argument, either a file called DirectoryName.info or a file called .info inside the directory will be used, depending on whether a path separator was specified at the end of the directory name or not – Impressive simply appends .info to whatever the input path name was.
In any case, the default file name can be overridden by the -I command line option.
Info scripts are actually Python scripts with full access to Impressive's global data structures and functions. (It is possible to write real interactive applications using info scripts.) Thus, they can modify a broad range of settings concerning Impressive. This manual will only cover the most basic ones.
The main part of an info script defines the properties of each page. At the moment, the following properties are defined:
titletransitionimpressive -l.transtime-T at the command line). It contains the integer time (in milliseconds) the transition to this page shall take.overviewFalse or 1/True) that specifies whether the page shall be included in the overview page. If this property isn't specified, it is assumed to be True.skipTrue if the page shall be skipped during the presentation.overview:True, skip:False will be accessible both by cycling through the pages and using the overview page,overview:True, skip:True will be silently skipped in the normal page cycle, but remain accessible from the overview page,overview:False, skip:False will appear in the normal cycle, but not on the overview pageoverview:False, skip:True will not be accessible at all.boxestimeouttimeout property is present and the page is shown, Impressive will automatically switch to the next page after the specified number of milliseconds. Normally, the timeout will only be effective the first time the page is shown unless wrap mode is used (command-line option -w or --wrap). This restriction makes it possible to create self-running presentations with individual per-page timeouts.radius--spot-radius command line option or run-time adjustments. Note that the value is not reset to the default value after the page has been left again.darkness--darkness command line option or run-time adjustments. Note that the value is not reset to the default value after the page has been left again.commentsoundvideoalwaysTrue, the media file specified in the sound or video properties will be played every time the page is entered, not just the first time.progress-d/--duration command line switch) will not be shown on this page. In practice, it might be useful to hide the bar from the first page so that it is not visible during the introduction.resetTrue, the timer will be reset each time this page is left, just as if the R has been pressed. If the special value 2 or FirstTimeOnly is used, the reset will only take place if the page was shown for the first time. Again, this is particularly useful on the first page: A combination of progress:False, reset:FirstTimeOnly makes it possible to set up the presentation long before it actually begins – the first page can be showed as long as desired, actual timing starts at the second page.rotate-r command line option: It specifies how the page shall be rotated, in 90-degree steps clockwise.OnEnter, OnLeave, OnEnterOnce, OnLeaveOnce~Once variants will only be executed when the page is entered or left for the first time. The callable must not take any arguments. This feature can be used to associate arbitrary Python code with specific pages, for example to execute external programs.keys'keys': { 'x': SomeFunction } will invoke SomeFunction() if the lowercase character 'x' is typed while the page is displayed. Regarding the functions, the same restrictions as for the OnEnter/OnLeave family apply: the function must not take any parameters and lambda functions can not be saved. Also note that it is not possible to overwrite Impressive's pre-defined key bindings with this method.invert--invert command-line switch does. It overrides the --invert setting on a per-page basis: If set to True, the page will always be inverted; if set to False, the page will never be inverted even if --invert has been specified on the command line.Note that in Impressive versions prior to 0.11.0, the transition and transtime properties defined the transition from the current page to the next, not from the previous page to the current one.
The properties are stored together in a Python dictionary called PageProps. The syntax looks like in this example:
PageProps = {
1: {
'title': "Title Page",
'transition': PagePeel,
'sound': "background_music.mp3"
},
2: {
'title': "Another Page",
'timeout': 5000
}
}
The PageProps definition (and only the PageProps definition) will be rewritten by Impressive if the S key is pressed. User-defined PageProps entries will also be left untouched, except for some pretty-printing.
The name of the presentation is shown in the title bar of the Impressive window (if not in fullscreen mode). By default, the file name or (if available) PDF metadata title will be used for this purpose, but the presentation title can also be explicitly set by overwriting the DocumentTitle variable:
DocumentTitle = "My Presentation"
Another useful variable, AvailableTransitions, contains a list of all transition classes that may be used for randomly assigning transitions to pages lacking the transition property. Thus, if a certain transition is undesired (either because of personal dislike or because it shall be used exclusively on pages where it is manually assigned using PageProps), something like the following can be written:
AvailableTransitions.remove(WipeBlobs)
On the other side, it's possible to activate transitions that are not enabled by default:
AvailableTransitions += [SlideUp, SlideDown]
Alternatively, AvailableTransitions can be completely overwritten to have the same transition (or set of transitions) assigned to all pages:
AvailableTransitions = [Crossfade]
Another use of info scripts is overriding the default or command-line settings on a per-file basis. This can be done by simply overwriting one of the variables that are defined at the beginning of impressive.py. Each of these variables corresponds either to a command-line setting, or to some constant related to visual appearance or performance. So, for example, to force fullscreen mode for a presentation, write
Fullscreen = True
The working directory while executing the info scripts themselves is always the directory in which the info script is stored in.
The base directory for external actions that originate from Page Properties or PDF hyperlinks is always the directory of the PDF or image file this page belongs to. In other words, if e.g. 'sound': "music.mp3" is written in the info script for one page of presentation.pdf, the file music.mp3 is expected to be located in the same directory as presentation.pdf.
Liviu Andronic is maintaining PPAs for Ubuntu that contain the newest stable and development versions of Impressive. They can be added using the commands
sudo add-apt-repository ppa:landronimirc/impressive (release versions) or
sudo add-apt-repository ppa:landronimirc/impressive-svn (nightly builds).
Joel Berger has written a Perl script that extracts transition information from special comments in LaTeX beamer source files and generates a Impressive info script from the gathered information: makebeamerinfo.
Juan Carlos Paco has written a very simple graphical interface for Impressive that runs on Debian and Ubuntu systems, called GUImpressive.
Another GUI comes from B. Pratibha, called »BOSS Presentation Tool«.
Impressive is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for any particular purpose. See the GNU General Public License for more details.
You can always contact the author of Impressive to send him ...