MagicLantern is released under the GPL: http://www.gnu.org/licenses/gpl.html

Please visit http://www.arachnoid.com/MagicLantern for more documentation and to acquire the latest version of MagicLantern.

NOTE: For formatting reasons, users may want to temporarily make the MagicLantern program frame larger to properly read these instructions.

Introduction | Overview | Preliminaries | First Steps | Image Scaling | Memory Problems | Editing in Depth | Display in Depth | Total Recall | Thumbnail/Scaled Image Issues | Miscellaneous Notes

Introduction

MagicLantern is a Java program that helps you organize, create, edit and present electronic slide shows. MagicLantern is compatible with commonly available remote controls that work with PowerPoint and other slide management and presentation programs, to create screen-filling "slide shows" of user-provided media. MagicLantern has an integrated image editor and organizer to manage creation of slide shows. MagicLantern supports automated slide presentations, with many user-specified properties.

Because MagicLantern is written in Java, it will run on virtually any platform. To run, MagicLantern needs a recent version of Java, available free at http://java.com.

Overview

Modern photographers acquire their images with digital cameras, and the resulting image quality is usually spectacular. When it comes time to present a slide show, presenters usually discover that available electronic slide projectors have a much lower resolution than their camera. And editing slide shows require tiny images called "thumbnails" to represent the full-size images, but that are easily moved about in an editing window. This means modern slide show editing needs three kinds of images:

1. The original, full-resolution images that came from the digital camera.
2. Smaller versions of the above for presentation by a typical modern electronic slide projector.
3. Tiny versions of the originals for use as tokens that can be easily moved about in an electronic slide organizer.

MagicLantern manages all these image types for you, and is able to create the second and third image types from the first. MagicLantern then allows you to design slide shows in an intuitive way, by dragging and dropping thumbnails from one place to another, or changing their order within your slide show.

Inexperienced digital photographers may wonder if it is necessary to keep the original, large, high-quality image files, since they cannot normally be used in their original form. Well, there are a number of reasons to keep an archive of large originals, as difficult and storage-consuming as they are:

• A large, highly detailed original can be cropped to produce what may be a better-composed image than the original, and the result can still have acceptable resolution.
• As time passes, slide projector software, and slide projectors, gradually support higher resolutions. This means presentation hardware may eventually catch up with the original resolution of your images.
• Someone might want to create a large poster out of one of your images, or you may be invited to publish an image in a magazine or newspaper. In both these cases, the original high resolution is required.

In the following sections you will learn how to organize collections of digital images, produce different versions for different purposes, and create professional-quality "slide show" presentations of your own.

Preliminaries

• Always maintain backups of your image library. MagicLantern won't ever erase any of your images, but it's good policy to maintain multiple copies of your files in separate locations.
• MagicLantern stores its results in plain-text files, most of which will be found on this system at (data path), which means if you want to use the results produced by MagicLantern, it is a simple matter of copying plain-text lists of image names from one place to another. What I am saying is MagicLantern doesn't use any cryptic, difficult-to-interpret file formats.
• While editing slide shows, remember that you can open your favorite file browser to a directory of images and drag thumbnail images from the browser directly into MagicLantern's editing window. MagicLantern knows what to do in this case — it automatically includes such images in its editing display and results. This means you can use your normal file browser's image listings as part of the editing process.
• If you have a modern digital camera and if you save images in a large image format, chances are MagicLantern won't be able to process the images easily, or present them in a slide show without unacceptable delays in loading new images. MagicLantern has a way around this problem — it can produce scaled down images that match the resolution of typical computer displays and electronic slide projectors, and that are easier to manage.

First Steps

In this exercise, we will open a directory of images in MagicLantern for editing. Remember that MagicLantern doesn't edit your images directly, it only manipulates image names in a list, and all the editing actions are performed against a list, not the original images. Your images are never deleted or modified by MagicLantern.

To start using MagicLantern, follow these steps:

• Locate a directory of graphic images.
• Run MagicLantern and click the "" (Create/Edit) tab.
• In the right-hand pane, click the icon that looks like this:  and navigate to your image directory. When you have opened the directory, you will see a list of labels that say "No thumbnail, create using 'Configure'" instead of the images you might expect. It seems that MagicLantern needs you to create some thumbnails, those tiny images mentioned above.
• To create thumbnails:
  • Click the "" (Configure) tab.
  • At the top panel, choose "Thumb" mode.
  • Click the "" (Path) button and browse to the same image directory you chose before.
  • Click "Start."
  • MagicLantern will create the required thumbnail images.
• Now return to the "" (Create/Edit) tab and (assuming all the above steps were followed correctly) the "No thumbnail" labels will be replaced by miniature copies of your graphic images.
• A bit of orientation. In the editing window, the left-hand pane holds your slide show, while the right-hand pane is a temporary scratch-pad area that contains images you are considering putting into your show.
• Before we can create a slide show, we must first open a new show file. At the top left, click the button that looks like this:  and type a name for your show.
• Now you can drag thumbnail images into your new show. Feel free to experiment with the editor, and don't worry about making mistakes at this stage. Remember that you are not manipulating your image library directly, just some tokens that represent images.
• Drag some thumbnail images into the left-hand window and experiment with them. Notice that you can drag the images around to change their order, or drag them out of the editing window entirely. You can select multiple images and drag them as a unit. You can even open your system's file browser and drag image icons from there into the MagicLantern editing window.
• If you create a result you don't like, simply press the "" (Undo) button to put things back as they were. Then, if you should reconsider, you can even redo something you have undone by clicking the "" (Redo) button.
• When you are satisfied with the result, press the "" (Save) button to save your show.

We'll return to the editor later, but because we've just created a show, we can take a preliminary look at MagicLantern's display features.

• Click the "" (Display) tab to move to the presentation slide viewer.
• At the top you will find a drop-down list that at the moment will probably display "-- Select show --".
• Open the list to find the name of the show you just created. Select it.
• The first slide in your show should appear in the display pane.
• Press the keyboard "Page Down" or right arrow key (or the button marked ) to move to the next slide.
• Press the keyboard "Page Up" or left arrow key (or the button marked ) to move to the previous slide.
• To change the display's appearance:
  • Press function key F3 for a normal sized display.
  • Press function key F4 for a larger display.
  • Press F5 for a full-screen display, and remember that you need to press F3 or F4 again to return from this full-screen mode.
  • While you are in the full-screen mode, the above-described slide show keys will continue to work.
  • By the way, function key F2 moves you to the editor tab, and function key F1 moves you to the help tab.

Image Scaling

The editing pane uses thumbnails to represent full-sized images, and thumbnails are rather small, so your system's resources won't get used up unless you place many hundreds of images in the scratchpad area or in your slide show. But when showing images using the "Display" tab, MagicLantern must load graphic images in their full, original size, and depending on the user's choices, this may lead to certain problems. It is at this point that we need to discuss the size of computer graphic images.

When a typical graphic image is stored, it is compressed, typically by a ratio of 7 to 1 or better. This makes graphic images seem smaller than they actually are and overlooks the fact that, to display an image, MagicLantern must first uncompress it.

For example, I have a large collection of nature images, taken with a modern digital camera. My camera creates images that are 3,888 by 2,592 pixels in size, and the images have a storage size of about 4 megabytes (the size varies from one image to another). As I was planning a predecessor to MagicLantern years ago, I thought "4 megabytes doesn't seem very large for a modern computer program, there shouldn't be any great difficulty in unpacking and displaying such an image."

I was quite wrong. As I designed that earlier program, I was reminded of the tremendous memory requirements of modern computer graphics. After being unpacked and put on display, a computer graphic image requires three bytes per pixel (one for red, one for green, one for blue). Remember that there are (width times height) pixels in such an image and each pixel is three bytes. So while it is unpacked, my 4 megabyte image is actually:

width x height x 3

— or —

3,888 x 2,592 x 3 = 30,233,088 bytes

If I had accepted this huge image size for a typical slide show, I would have prevented many owners of small systems from using MagicLantern. So instead I came up with a three-tiered image scheme:

• The original, large image, which for reasons provided above should be preserved in its original size.
• An intermediate scale, equal to the resolution of a typical computer monitor or slide projector, for display purposes.
• A tiny scale, for use as thumbnails — little image tokens used in editing.

MagicLantern manages this scheme for you — if you visit the "" (Configure) tab, you will notice that the "Scaled Image Generator" at the top can create intermediate-sized images as well as thumbnails. For a reliable slide show presentation on a system without vast amounts of memory, the user should create both intermediate-sized images and thumbnails, through this procedure:

• Select the "" (Configure) tab.
  • Select the "Scaled" mode.
  • Choose a scale or accept the default — the chosen scale should be approximately the same as your display device's width in pixels, or a bit larger.
  • Click the "" (Path) button and navigate to the image directory of interest.
  • Click "Start". The scaled images will be created and placed in a subdirectory named "MagicLanternScaledImages".
• Now select the "Thumb" mode.
  • Choose a scale or accept the default.
  • Click "Start". The thumbnails will be created and placed in a subdirectory named "MagicLanternThumbnails".
• (Always create the scaled images before the thumbnails.)
• Now move to the "" (Create/Edit) tab.
  • At the right-hand pane, click the "" (Open) tab
  • Navigate to the image directory, then choose the subdirectory named "MagicLanternScaledImages". The right-hand pane will show scaled versions of your full-size images.
  • Create your slide show using these scaled images instead of the originals.

This scaling procedure assures that the MagicLantern slide display routines won't take forever to load and display your images, the fade transition effect will work as intended, and MagicLantern won't halt with an "Out of Memory" error, our next topic.

Memory Problems

Despite the above instructions, it is virtually certain that MagicLantern users will sometimes have memory problems. One reason is that, while creating intermediate-scale images and thumbnails, MagicLantern must load the original full-size images in order to scale them.

There are several ways to detect that memory has become an issue:

• If you visit the "" (Configure) tab and see the bottom "Memory Statistics" pane all lit up in red digits , there is a memory problem.
• If a dialog appears saying something like "MagicLantern is very low on memory ..." and directing the user to this part of the help file, there is a memory problem.
• If smoke starts pouring out of your computer accompanied by the sound of unhappy orphaned gerbils ... okay, just kidding.
• If MagicLantern becomes unresponsive and/or refuses to show a slide, there is a memory problem.

Remedy for Windows XP

Under Windows XP, the user may notice that the "Maximum" memory amount listed under "Memory Statistics" is about 66 megabytes. This is not remotely adequate — it's the size of two typical camera images, with nothing to spare. The following procedure should provide an adequate amount of memory on Windows XP systems:

• Open a file browser.
• Select "Tools ... Folder Options ... File types"
• To save time, when confronted by the list of file types, type "j" at the keyboard. In most cases this will jump to "JAR", the file type of interest. If not, scroll down to get to the entry for "JAR".
• Click "Advanced", then "Edit".
• After the string "javaw.exe" and before the string "-jar", put this: "-Xmx1000m".
• The section of interest should now look like this: "(path)/javaw.exe -Xmx1000m -jar (path to MagicLantern)".
• Click "OK, "OK" and "Close".

Now run MagicLantern again, and you should see a maximum memory amount of roughly a gigabyte, even if your system doesn't have that much memory.

The technical explanation is that the Windows Java runtime engine doesn't allocate enough memory for a modern non-toy computer program, and Sun Microsystems should be ashamed of themselves.

Remedy for Linux, Macintosh

The problem described above doesn't usually come up on these operating systems — they normally grant sufficient memory to the Java runtime engine by default. But if a memory problem should come up, a similar solution applies:

• Locate the shell script responsible for launching MagicLantern and open it in an editor.
• There will be a line that looks something like this: "java -jar MagicLantern.jar".
• Change this line to: "java -Xmx1000m -jar MagicLantern.jar" and save the file.

Values greater than 1000m (1 gigabyte) can be entered and some of them will work, but these excursions should be reserved for cases where there is an actual need.

Here is a summary of this issue. If you click "" (Configure) and examine the memory statistics, you will see at a glance whether you are going to have memory problems:

• If the value for "Allocated" memory is substantially smaller than the value for "Maximum" memory, there isn't a problem.
• If the value for "Allocated" memory gradually approaches the value for "Maximum" memory, solutions like the above should be applied or the user should use scaled display images, or both.
• If the value of "Allocated" memory equals the value for "Maximum" memory, there is an immediate problem that should be addressed before commencing serious work with MagicLantern. See above for a remedy.

Editing in Depth

Let's explore the editor and its functions in greater detail. We've already covered the basics — the right-hand pane is meant to contain a collection of slides to consider for inclusion in a slide show, and the left-hand pane contains your developing slide show. Here are some details:

When you drag a thumbnail image, you determine whether the action is a move or a copy by holding down the control key. If you want to move an image (e.g. remove it from its original location), don't hold the control key down. If you want to copy an image, hold down the control key as you drag the thumbnail — the dragging cursor changes to indicate that it is a copy.

• Dragging and dropping thumbnails is just one way to control the editing process — there is also the option of cutting and pasting. The user can select one or more slides and cut, copy or paste using the buttons on the toolbars, or a right-click context menu, or the standard keyboard commands:
  • Ctrl+X = Cut
  • Ctrl+C = Copy
  • Ctrl+V = Paste
• To preview a slide in full scale, just double-click it. To exit the preview and return to the editor, just click the image.
• To view details about an image, right-click it and choose the "" (Info) menu option. The resulting dialog lists the image's location, width, height, storage size, uncompressed size, and other details.
• Remember that the right-hand scratchpad panel is just one source for images — your favorite file browser is also a perfectly suitable way to locate and transfer images. While browsing image directories using your normal file browser, preferably set up to show icons, simply click an image and drag it into the MagicLantern editor panel. Many users may prefer using their file browser over the built-in scratchpad panel. Or they can be used together — the scratchpad can be used to collect images from your file browser before being selected for your show.
• If the user follows the advice of these instructions and uses scaled rather than full-size images for slide shows, they are easy to identify — when using the context-menu "" Info menu item, each of the scaled images has a prefix of "scaled_", so the source of the images can be confirmed. Also, a short version of each image's filename can be seen by hovering the mouse over an image's icon.
• MagicLantern can detect duplicate slides in your show, a common problem as slide shows become complex. Just click the "" (Search) button — MagicLantern will scan your slide show and list any duplicates it finds along with their index numbers.
• To change the number of columns in the editing display, open the "Choose Display Columns" drop-down list at the upper right of the editing pane and select a different number. Some people prefer a single long column, others like the default of three thumbnails in a row, some prefer even more, and this depends to some extent on the size of the thumbnails (see below for a section on changing thumbnail size) and the resolution of the computer display.
• If you provide an estimate for how long each slide will be on display, MagicLantern will predict your show's duration in hours, minutes and seconds (and if your show can be measured in hours, you're in trouble). Just enter an average time for a typical slide to be on display, and MagicLantern will automatically update its estimate of total show time on the editing toolbar. As you add and remove slides, this estimate changes automatically.
• If the editing process is completed or if the user wants to review the show periodically, it is a simple matter of pressing the "" (Save) button and moving to the "" (Display) tab, where the show will be updated and ready for viewing.
The editing pane (at the right) saves files under particular names, and those names appear in the display pane for easy reference. The scratchpad pane (at the left) doesn't have a file-save feature, but its contents are saved automatically in a file located on this system at (browse path).

Display in Depth

Now we look at display issues in a bit more detail. The user might want to present a slide show using a media projector, or a large computer monitor, or even on a media center with a large flat-panel TV. MagicLantern can handle all these options.

There are three basic display modes that control the size of the image on the computer video display:

• Normal mode, partially covering the screen and with a size determined by the user, controlled by function key F3.
• Maximized mode, covering the entire screen except toolbars and menu along the edges, controlled by function key F4.
• Full-screen mode, completely covering the screen including the edges, controlled by function key F5.

In full-screen mode, function keys are used for control because the mouse is unavailable. Remember — to recover from full-screen mode, press any of the function keys F1, F2, F3 or F4. While in full-screen mode, these control keys are available (a more complete list of MagicLantern keys appears in the "Miscellaneous Notes" section below):

Key(s)	Function
Home	Jump to the start
Left-arrow/Up-arrow/Page Up/P/Backspace	Prior slide
Right-arrow/Down-arrow/Page Down/N/Space bar	Next slide
End	Jump to the end
Period (".") or B	Blank/unblank the screen
Enter or Escape	Context switch (see below)

Context Switching

The term "context switch" (Enter or Escape) will require a word of explanation. MagicLantern has two show indices and the user can switch between them using the indicated keys (which happen to be keys commonly available on slideshow remote controls). The reason? In my slide shows I discovered that I wanted to switch between the normal sequence of slides and a map or chart, then switch back again without losing my place. So I added a feature that jumps out of the main body of my presentation to some charts located at the beginning of the sequence. The simplest way to implement this feature is to have two indices (counters) pointing to two different locations in the slide sequence, and an easy way to switch between them. Both indices are fully and independently controllable, and it's child's play to switch between them.

On first hearing this, some readers may think it's sort of a gimmick, but after using it a few times, they won't be able to get along without it. During side shows I am often asked how I manage to bring up a chart at any point during the show, and I have to explain that I wrote my own software to get the feature.

Auto Show

MagicLantern has an automatic show feature that displays a slide show unattended, with user-specified delay times (set using the "" (Configure) tab / Auto Show Side Duration) and the option to repeat the show endlessly. Once the desired options have been set, simply press the "" (Auto-Show) button to start the show.

Fade Transition

Rather than cut directly from one image to another, MagicLantern has a fade transition option that dissolves one image into another, with controls located at the "" (Configure) tab:

• Transition fade duration milliseconds, default 800 (that's 8/10 of a second). This selects the time required for the transition, obviously a subjective judgment.
• Transition steps, default 20. Increasing the number of steps makes the transition smoother, but requires more computer power. Too small a number produces a jumpy transition that undercuts the goal of the transition.
• Enable Fade Effect check-box, default disabled. Some slow systems won't be able to produce an aesthetically pleasing transition, so this feature can be disabled.

Constant Aspect Ratio

MagicLantern maintains the original aspect ratio of your images, regardless of the display size or shape. MagicLantern will never stretch or otherwise distort your images, which means there will sometimes be black bars at the left and right, or top and bottom, of some images. This is intentional (it's a feature, not a bug), and to be frank, it is more difficult to produce an image with aspect ratio fidelity than it is to let the display's size and shape distort the images.

Image Size Issues

Earlier we discussed the issue of image size with respect to avoiding memory problems. But it turns out that an image size optimized for a particular display has advantages in display update speed and even the appearance of the fade transition. Typically I create scaled-down images one standard display size larger than my media projector (mine has an image size of 1024x768, so I create 1280x1024 images, and that is the default size in MagicLantern), because this extra size avoids minor image artifacts one sees in images that are identical to the size of the display.

If memory limitations exist, users may want to create images the same size as their display, in which case there are options to minimize the distortions inherent in this process. One way to improve the appearance of scaled-down images is to explore the quality level option in the scaled image generator located on the "" (Configure) tab. The options are named "Good", "Better", and "Best", but to be technical for a moment, they correspond to three image interpolation strategies:

Name	Corresponds to
"Good"	Nearest Neighbor
"Better"	Bilinear
"Best"	Bicubic

The better interpolations tend to take longer while generating images, but have no effect on the subsequent load and display speeds. Read more about this rather technical topic here.

Industry Standard Controls

Because most multimedia projectors must work with Microsoft PowerPoint (there is no connection whatever between MagicLantern and either Microsoft or PowerPoint), a standard set of control keys has come into existence and are honored by the majority of multimedia projectors and remote controls. Because MagicLantern honors this same set of controls, chances are if a user already has a multimedia projector with a remote control, or owns a wireless remote control independent of his projector, it will be able to control MagicLantern (and if this is not the case, if I have overlooked a control method, please post to my message board and tell me about it).

Sound Effects

MagicLantern has a feature that can tie a displayed slide with a sound effect by way of a special editing action that associates a sound with a slide.

As an example, I recently gave a slide show about birds I had photographed, and I thought it would be nice to accompany the pictures with bird calls. While editing my slide show, after I had selected a slide to put in my show, I clicked the slide, then used the context menu (right-click) item "Add Sound" to navigate to a directory where I keep my show sounds, and chose an MP3 file to play when that slide is on display.

The sound associations are saved along with the slide show. To remove a sound association, in the slide show editor simply right-click a slide and choose "Remove Sound".

Total Recall

When you exit the program, MagicLantern remembers everything — the size and shape of the program frame, your choices and option settings, which slide shows were on display and being edited, even the current settings of the slide show controls. This means you can set up a slide show just as you want, exit MagicLantern, and start the show by simply clicking on the MagicLantern icon.

For example, if you want a trouble-free slide show launch, just set things up the way you want including options such as full-screen or auto-show, then press function key F12, which exits the program. Then, when it's showtime and you restart MagicLantern, everything will be restored including full-screen mode, and if you chose auto-show, the auto-show will commence.

The configuration file that contains all the MagicLantern settings is a plain-text file located on this system at (configuration path).

Thumbnail/Scaled Image Issues

Changing Thumbnail Size

The user might want to change thumbnail size from the default of 120 pixels (which means a box 120 pixels on a side, into which the scaled image fits). But such a change means all existing thumbnails will be recreated. For a large image collection this activity might be better carried out during idle time, because the time required to recreate all the thumbnails can be substantial.

To change thumbnail size, click the "" (Configure) tab, and select the "Thumb" mode. Choose a new size, click the "" (Path) button and navigate to the directory where your images are stored. Now click "Start" to begin the generation process. The scaled image generator will scan the selected directory and all subdirectories, creating thumbnails in all cases where there is no existing thumbnail with the right size. This might take some time.

Rescanning your Image Collection

As you add images to your collection, it is a good idea to run the scaled image generator periodically (or you can wait until you see the message "No thumbnail" instead of a thumbnail). The generator is reasonably intelligent and will only create scaled images (thumbnails and presentation images) for cases where:

• There is no existing scaled image.
• An existing scaled image is the wrong size.
• The source image has a newer date than the scaled image.

Sometimes, after making a lot of changes to your image collection, it might be more efficient to delete the thumbnail subdirectory (always named "MagicLanternThumbnails") and the scaled image subdirectory (always named "MagicLanternScaledImages") then use the scaled image generator to regenerate them.

Miscellaneous Notes

MagicLantern accepts two graphic file formats, "jpeg" (Joint Photographic Experts Group) and "png" (Portable Network Graphics). The first type is recognized with two file suffixes — "jpg" and "jpeg" in upper or lower case, while the second is recognized with just "png", also case insensitive.

If you find a bug in MagicLantern, please visit http://arachnoid.com/messages and leave a report.

Here are the keyboard keys defined in MagicLantern and their corresponding actions:

Key(s)	Action
Function key F1	Switch to Help panel
Function key F2	Switch to Edit panel
Function key F3	Switch to Display panel, normal size
Function key F4	Switch to Display panel, maximized
Function key F5 (first press)	Switch to Display panel, full-screen
Function key F5 (subsequent presses)/Escape	Context switch (jump to other slide sequence)
Function key F6	Show/hide screen boundary square
Function key F7	Switch to configure panel
Function key F8	Start/Stop auto show
Function key F12	Exit MagicLantern
Home	Jump to beginning of slide sequence
End	Jump to end of slide sequence
Backspace/P/Left Arrow/Up Arrow/PgUp	Move to previous slide
Space bar/N/Right Arrow/Down Arrow/PgDn	Move to next slide
Period (".")	Blank/unblank screen

Here are some MagicLantern-related resource locations:

Resource	Location
MagicLantern Home Page	http://arachnoid.com/MagicLantern
MagicLantern version	(version)
User home directory	(user home directory)
MagicLantern data directory location	(data path)
MagicLantern configuration file location	(configuration path)
Currently running MagicLantern application location	(application path)
Scratchpad panel content file location	(browse path)