T
a
b
l
e

o
f

C
o
n
t
e
n
t
s
imjSlideshow
Documentation 0.1

Overview

imjSlideshow is an open-source-GUI-programm to create slideshows from images and text. Images and text can be combined in many ways and can be provided with effects like move, scale, rotate and crop. The effects can be parametrized in the time axis so that variety of transition effects are possible.
imjSlideshow is released as open-source program under the GNU GPL Version 3. It uses imageMagick and ffmpeg to render the slideshow and is written in Java.
imjSlideshow was inspired by dvd-slideshow, a command-line utility to create slideshows.
imjSlideshow is available in the following languages:
english
deutsch

Components of a slideshow

A imjSlideshow consists of images and modifications.

Image

An image is either an image from an image-file or an image generated from text.
An image can contain modifications and other images. Other images are drawn on top the previous image.

Modification

A modification changes the image as either a whole or adds additional images.
The result is a tree of images and modifications.

Templates

An image or a modification is based on a template. A template has parameters of specific types and a fixed number of point in times. Appendix A lists all possible templates with its parameters.

Point in time

A image or a modification starts and ends at a specific point in time. The parameter of the image or the modification can define additional point in times. The values of the parameters can change at this point in times.

Duration

Between the point in times of a image or a modification are the durations.

Parameter

A template defines specific parameter. A parameter has a type and defines the point in times at which the parameters can be changed and at which duration the values of the parameter are used and valid.

Layout

imjSlideshow shows the slideshow in a quarter-view.

component-view-part

The component, that is selected in the tree-view or the timeline, is shown in the top-left quarter. All parameters at defined point in times can be edited. For details look at the component-view and -editor.

preview-part

A preview can be shown in the top-right quarter. (planned)

tree-view-part

The components of the slideshow are shown in the bottom-left quarter in a tree-view. Root is the slideshow and the root-images. For details look at the tree-view.

timeline-view-part

The components of the slideshow are shown in the bottom-right quarter as timeline. Each image and his children - images and modifications - is shown in a rectangle. For details look at the timeline-view.

Menu and Toolbar

Menu

File
new slideshow
open slideshow
---
save slideshow
save slideshow as
save all slideshows
---
close slideshow
---
render
---
edit properties
copy files to directory
---
close all slideshows
Edit
---
Extra
---
Slideshows
other slideshow
...
Help
about

Toolbar

new slideshow open slideshow save slideshow render cancel rendering Rendering messages and progressbar

Menu- and Toolbar-Elements

new slideshow

Creates a new empty slideshow

open slideshow

Shows a filechooser, opens the selected slideshow and shows it in a new window.

save slideshow

Saves the slideshow. If no filename are given previously, a filename can be selected in a file-chooser.

save slideshow as

Saves the slideshow under an other filename. A new filename can be selected in a file-chooser

save all slideshows

Saves all open slideshows. For all slideshows without a filename, a filename can be selected in a file-chooser

close slideshow

Closes the slideshow. If the slideshow are changed, a message-box is shown with the possibility to close without saving, close with saving or cancel the closing. If the last slideshow is closed, than the application terminates.

render

Renders the slideshow in a background process. A cancel-button, messages and a progress-bar is shown in the toolbar. If a render-process for the slideshow is in progress, you cannot start another render process. For details look at the render-process.

edit properties

Edits the properties of the slideshow. It is the name of the slideshow, the output-format and the action that is taken for selected files. For details look at the properties view.

copy files to directory

Copies all needed files into the directory where the slideshow is saved. For details look at 'copy files to directory'.

close all slideshows

Closes all slideshows. For all slideshows, that have unsaved changes, a message-box is shown with the possibility to close without saving, close with saving or cancel the closing. If all slideshows are closed, than the application terminates.

other slideshow

All open slideshows will appear in the menu. To jump to a slideshow, clicking at its entry.

about

Shows an about-dialog and shows the version.

cancel rendering

The cancel-rendering-button cancels the current rendering-process. It is only shown, when a rendering-process is active. For details look at the render-process.

Rendering messages and progress-bar

If a rendering-process is active, a message and a progress-bar is shown. The message consists of the frames rendered, the total count of frames to render and a factor of the duration of the render process relative to the duration of the resulting slideshow-video. For details look at the render-process.

Component-view and -editor

In the component-view, all parameters of an image or a modification can be viewed and edited.
At the beginning type, name, template, start time and duration are displayed. Name, start time and duration can be changed.
In the center all parameters of the image or modification are listed. In the time-areas in which the parameters can have a value, the value can be edited. In the areas which are provided with a leftward triangle, the value of the following time span is valid. In the areas which are provided with a triangle pointing to the right, the value of the preceding time span is valid. For a time range there is no value provided or required, nothing is displayed.
At the bottom of the table the points in time are displayed in a row, the time duration are displayed in another row. Both, points in time and time duration can be changed.
How the points in time and the time durations can be edited, is explained at edit capability of time- and duration-fields.

Tree-view and -editor

The components of the slideshow are shown in a tree in the tree-view.
If a image or a modification gets the focus, it is shown in the component-view and is selected in the timeline-view.
It can be more than one component selected with the standard-methodes:
Click with shift-down: all components between the first and the last selected component are selected.
Click with ctrl-down: the clicked component is added or removed from the selected components.
The nodes can be expanded and collapsed.
The selected nodes can be dragged an dropped into the tree-view or the timeline-view. For details look at drag and drop - cut and paste.
A popup-menu can be shown for the selected component. For details look at popup-menu.

Timeline-view and -editor

In the upper left corner are 4 buttons to change the time to pixel factor:
Zoom in The time to pixel factor is doubled
Zoom out The time to pixel factor is halved
Zoom fit The time to pixel factor is set to a value, that the whole slideshow is shown in the timeline-view
Zoom 100% The time to pixel factor is set to a value, that every frame is shown as 2 pixels

A time-grid is shown in the column-header. A red line shows the time, where the cursor pointed to. Green lines shows the begin and the end of the selected component that is shown in the component-view.
The components are shown in the scroll-area. Every component is shown as a rectangle. The position and the width of the rectangle reflects point in time and duration of the component. Any additional point in time is displayed as a small bar. If the component has a thumbnail, it is shown in the left of the rectangle. Beside the thumbnail the name is written.
The components can be selected. They are selected in the tree-view too. The last selected component is shown in the component-view .
It can be more than one component selected:
Click with ctrl-down or shift-down: the clicked component is added or removed from the selected components.
Double click: the component and all its children are selected.
The point in times of the selected components can be modified:
If the cursor is over the begin, the end or a intermediate point in time of a selected component, the cursor is changed to a red arrow. While the left mouse-button is down, the point in time under the cursor can be moved.
If the point in time under the mouse is the begin of the components, than the components are moved and unselected components, that are temporal after the selected components, are moved too.
If the point in time is not the begin of the components, than the duration of the components are increased or decreased and unselected components, that are temporal after the selected components, are moved.
The selected components can be dragged an dropped into the timeline-view or the tree-view.
For details look at drag and drop - cut and paste.
A popup-menu can be shown for the selected component. For details look at popup-menu.

Preview-view

planned

Render

The rendering is computed in a background-process.
The rendering can be canceled with a cancel-button in the toolbar.
While a rendering-process is active, no second rendering-process for the same slideshow can be started.
If a rendering-process is active, a message and a progressbar is shown in the toolbar. The message consists of the frames rendered, the total count of frames to render and a factor of the duration of the render process relative to the duration of the resulting slideshow-video.
There is one process for ffmpeg and one process that creates the frames in a rendering pipeline with imageMagick. Several files are temporary written into a newly created temp-directory.
After the rendering, the resulting video-file is copied to the directory, where the slideshow resides.

Properties-view

The properties of the slideshow can be edited in the properties-view.

Name

A name for the slideshow can be set.

Output Format

The output-formats can be selected. There are several PAL- and NTSC-formats

File action

This file-actions take place, if a image or modification contains a file-parameter and a new file is selected.

do nothing

No action is performed

ask

If a file is selected, it will be ask whether the file is copied to the slideshow-directory or not.

copy to directory

If a file is selected, copy it to the slideshow directory.

Copy files to directory

All files from all file-parameters are copied into the directory of the slideshow.
This is usefull, if you want to pack the slideshow with all necessary files into an archive.

Edit capability of time- and duration-fields

Point in times and durations are shown in fields with time-value and frame-count. The frame-count is calculated from time and the frame-rate of the output-format of the slideshow.
hh:mm:ss.SSSS/f
hh: hours if hours are zero, it is omitted. Leading zeros are omitted.
mm: minutes if hours and minutes are zero, it is omitted. If hours are omitted, leading zero are omitted.
ss. seconds if minutes are omitted, leading zero are omitted.
SSSS milliseconds with trailing zeros
f frame-count calculated from time and the frame-rate of the output-format of the slideshow.
The time can be edited. Depending on whether a dot or a colon is entered, the value entered is either a frame-count or a time-value. When only digits are entered, this is a frame count. When a dot or a colon is entered, this is a time-value.

Popup-menu

Popup-Menu for slideshow
new image-template at begin
at end
... at begin
at end
Popup-Menu for image
new image-template before
at begin
at end
after
... before
at begin
at end
after
new modification-template before *)
at begin
at end
after *)
... before *)
at begin
at end
after *)
Move image up
Move image down
Remove this image
Remove all selected
Popup-Menu for modification
new image-template before
at begin
at end
after
... before
at begin
at end
after
new modification-template before *)
at begin
at end
after *)
... before *)
at begin
at end
after *)
Move modification up
Move modification down
Adjust
Remove this modification
Remove all selected
new ... before A new image or modification is inserted before the selected component *)
new ... at begin A new image or modification is inserted as first child of the selected component
new ... at end A new image or modification is inserted as last child of the selected component
new ... after A new image or modification is inserted after the selected component *)
move up Moves the component up within its parent
move down Moves the component down within its parent
remove this ... Removes the component
remove all selected Removes all selected components
adjust Set the point in time and the duration of the modification to the point in time and the duration of the parent-image
*) Modifications can only added before and after, if the anchor-image is within another image.

Drag and drop - cut and paste

Selected images and modifications in the tree- or the timeline-view can be dragged and dropped. The drop-action can be choicen from a popup-menu after releasing the mouse.
copy copies the selected components at the drop-location
copy - move following copies the selected components at the drop-location and
moves following images and modifications according the duration of the inserted components.
move moves the selected components to the drop-location *)
move - move following moves the selected components to the drop-location
moves following images and modificatons accourding the duration of the inserted components *)
*) Move is only possible, if the drag and drop is performed in the same slideshow.
If the drop is outside of imjSlideshow , than the data is an xml-document with all selected components with all parameters.

xml-schema

imjSlideshows are stored as xml-files. imjSlideshow.xsd contains the schema for the xml-file.


Appendix A: Templates

Templates for images

Image

Shows an image from a image-file. The image-file is resized to the slideshow-size.
Point in times
Start- and end-point-in-time. All parameters are defined at the beginning point in time and are valid until the end.
Parameter Type Description
Image-File ImageFile The image-file that is shown.

The rendering uses the "composite"-operation of ImageMagick.

Composite Image

Shows an image from a image-file. The size of the image is adjusted according to the parameters.
Point in times
Start- and end-point-in-time. All parameters are defined at the beginning point in time and are valid until the end.
Parameter Type Description
Image-File ImageFile The image-file that is shown.
Fit to frame size Boolean If set to true then the image is resized to the size of the slideshow otherwise it is drawn as is.
Compose Compose It defines the mode of composition of the composite image with the result of the previous images and modifications.

The rendering uses the "composite"-operation of ImageMagick.

Text

Shows a text.
Point in times
Start- and end-point-in-time. All parameters are defined at the beginning point in time and are valid until the end.
Parameter Type Description
Text String The text to be shown.
Font Font The font of the text.
Point-size PointSize The point-size of the font.
Color Color The Fill-Color of the font.
Stroke-width Integer The stroke-width of the font.
Stroke-color Color The stroke-color of the font.

The rendering uses the "draw"-operation of ImageMagick.

Templates for modifications

Crop

Crops the resulting image.
Point in times
It defines 4 point in times.
From start to 2. point in time the same value take place. Between the 2. and the 3. point in time the value is interpolate. From the 3. point in time to end the same value take place.
Parameter Type Description
Type Type Type of the x-, y-, width- and height-value: percent or pixel
X Double The x-coordinate of the center of the region to be croped
Y Double The y-coordinate of the center of the region to be croped
Width Double The width of the region to be croped
Height Double The height of the region to be croped
Aspect Ratio AspectRatio Whether the aspect ratio is to be respected
Interpolation Interpolation The interpolation to be used

The rendering uses the "crop"-operation of ImageMagick.

Scale

Scales the resulting image.
Point in times
It defines 4 point in times.
From start to 2. point in time the same value take place. Between the 2. and the 3. point in time the value is interpolate. From the 3. point in time to end the same value take place.
Parameter Type Description
Type Type Type of the width- and height-value: percent or pixel
Width Double Scale-factor of the x-axis
Height Double Scale-factor of the y-axis
Interpolation Interpolation The interpolation to be used

The rendering uses the "resize"-operation of ImageMagick.

Move

Moves the resulting image.
Point in times
It defines 4 point in times.
From start to 2. point in time the same value take place. Between the 2. and the 3. point in time the value is interpolate. From the 3. point in time to end the same value take place.
Parameter Type Description
Type Type Type of the x- and y-value: percent or pixel
X Double The x-value to be moved in the x-axis
Y Double The x-value to be moved in the y-axis
Interpolation Interpolation The interpolation to be used

The rendering uses the "geometry"-operation of ImageMagick.

Rotate

Rotates the resulting image.
Point in times
It defines 4 point in times.
From start to 2. point in time the same value take place. Between the 2. and the 3. point in time the value is interpolate. From the 3. point in time to end the same value take place.
Parameter Type Description
Angle Double The angle to be rotate in degrees
Interpolation Interpolation The interpolation to be used

The rendering uses the "distort SRT"-operation of ImageMagick.

SRT

Scales, rotates and moves the resulting image.
Point in times
It defines 4 point in times.
From start to 2. point in time the same value take place. Between the 2. and the 3. point in time the value is interpolate. From the 3. point in time to end the same value take place.
Parameter Type Description
Type Type Type of the x-, y-, scale-x, scale-y, new x- and new y-value: percent or pixel
X Double The x-coordinate of the point for rotation relative to the center
Y Double The y-coordinate of the point for rotation relative to the center
Scale X Double The scale-factor in the x-axis
Scale Y Double The scale-factor in the y-axis
Angle Double The rotation in degrees
new X Double The x-value to be moved in the x-axis
new Y Double The x-value to be moved in the y-axis
Interpolation Interpolation The interpolation to be used

The rendering uses the "distort SRT"-operation of ImageMagick.

Transparency

Transparents the resulting image.
Point in times
It defines 4 point in times.
From start to 2. point in time the same value take place. Between the 2. and the 3. point in time the value is interpolate. From the 3. point in time to end the same value take place.
Parameter Type Description
Transparency % Double The percent of transparency. 0=solid, 100=full transparent
Interpolation Interpolation The interpolation to be used

The rendering uses the "evaluate substract"-operation of ImageMagick.

Appendix B: Types

Types, that are used for the values of parameters.

AspectRatio

How the aspect ratio is respected.
Max preserved Maximum values of height and width given, aspect ratio preserved.
Min preserved Minimum values of width and height given, aspect ratio preserved.
Ignored Width and height emphatically given, original aspect ratio ignored.
Preserved one higher Change as per "Max peserve" but only if an image dimension exceeds the specified dimension.
Preserved both higher Change as per "Max peserve" but only if both image dimension exceeds the specified dimension.

Boolean

Color

Compose

Following compositions are available:
Source, Destination, Clear, XOR,
Src-Over, Src-Inside, Src-Outside, Src-ATop,
Dest.-Over, Dest.-Inside, Dest.-Outside, Dest.-ATop,
Multiply, Screen, Plus, Add,
Minus, Subtract, Difference, Exclusion,
Darken, Lighten
For details look at the examples of imageMagick.

Double

A floating-point number with "double"-precision.

Font

All fonts that knows imageMagick.

ImageFile

Holds an image-file. In the slideshow-xml-file the image-file-path is written. If the file is in the directory or in a sub-directory of the slideshow-file, than only a relative file-path is written.

Interpolation

Divided Difference Divided Difference interpolation
Left Returns the left value
Linear Interpolates linear between the values
Loess Locally weighted scatterplot interpolation
Neville Neville''s algorithm
Right Returns the right value
Spline Spline interpolation

Integer

PointSize

String

Type

The type of the x-,y-,width- or height-value. Either Percent or Pixel.