Almara User's Guide

Almara project, http://almara.sourceforge.net/
(c) 2005 Almara team

Contents

1 Overview
1.1 What is Almara?
1.2 Almara components
1.2.1 almara, the album organizer
1.2.2 almara_album, the image viewer and editor
1.2.3 almara_cht, the hidden heart of Almara
1.2.4 Other Almara modules
2 Managing your albums with almara
2.1 Creating your first Almara album
2.2 What has been created?
2.3 Menu tree
2.3.1 The File menu
2.3.2 The Search menu
2.3.3 The Album menu
2.4 Other controls
2.4.1 Sorting the album list
2.4.2 Other
3 Viewing and editing images with almara_album
3.1 The image list
3.2 The exif widget
3.3 The image area
3.3.1 Zoom modes
3.3.2 Histograms
3.4 Image operations
3.4.1 Simple image operations
3.4.2 Brightness/saturation/hue
3.4.3 Scale
3.4.4 Irreversible operations
3.4.5 Exporting operations
3.4.6 Cropping and panning
3.5 Album operations
3.5.1 Repeating and undoing operations
3.6 Movie operations
3.7 Copy and paste
3.8 The progressbar
3.9 The configuration dialog
3.9.1 Autosave interval
3.9.2 Resolution of previewed image
3.9.3 Cache and scheduler policy
3.9.4 Arrows behaviour and wrapping over the image list
3.10 The Display dialog
3.11 Widget docking
3.12 Configuration files
4 Printing with almara_print
4.1 The Layout tab
5 Getting and installing Almara
6 Epilogue

1 Overview

1.1 What is Almara?

Almara is a program suite designed primarily for digital still camera users. It can be used to organize your photo collection into albums, perform simple operations and enhancements on the images, browse your albums, print or export your albums to the web, do simple motion jpeg editing, and more.

Most programs widely used to achieve these tasks suffer from one common problem: losing bits of information on the way. Most operations you do with your images, will irreversibly decrease their quality. Cropping out a portion of your image will lose whole parts of your image; most images will be loaded and saved over and over again using the lossy jpeg compression, which makes the situation even worse. Keeping a separate copy of the original image adds chaos and storage overhead.

Unlike most commonly used programs, Almara will preserve the originals of your images. All image operations that you perform are only logged in what we'll call an album file. Next time the modified image is needed, Almara will quietly perform all the operations again.

Without elaborate operation scheduling, optimisations, and caching, this approach would make the program way too slow to be used. The effort that has been put into tackling these challenges has allowed us to present you with a program that is fit for everyday use on your desktop.

1.2 Almara components

1.2.1 almara, the album organizer

This is the program a typical user will start with. It lets you browse, create and delete albums.

An album is a fundamental object for all Almara components. Basically, it's a directory with images, containing a special album file -- a plain text file called album.alb that stores information about all the images in the album: names, descriptions, keywords, the log of all operations that have been performed on the individual images, as well as information about attached sound files. The album file also contains global information about the album itself, like title, description, creation date, owner, and other optional user-defined data.

almara will create albums from plain directories containing your images. It keeps a record of all albums you have created or used, and will present them to you, in a graphically appealing environment, previewing their contents with thumbnails.

Once you've selected an album to work with, almara will open it for you in almara_album. Motion jpegs can be opened in the same way.

1.2.2 almara_album, the image viewer and editor

This is the module you will spend most of the time with. It will let you browse a selected album. All the images are neatly previewed in a narrow column, showing a thumbnail, filename and description for each image in the album.

The bottom of the screen will show detailed information about the selected image. You can define and modify some of these fields (e.g. description); others are obtained from the image's exif header

Of course, most of your screen will be occupied by the image itself. The menu and toolbar offer a rich choice of image operations and enhancement filters. Should they not suffice, you can always use an external editor (this has a catch, see the detailed almara_album chapter for details). External programs can also be run to edit or play optional audio files attached to images.

You may select more than one image and preform operations on all of them. Some operations can also be performed on the whole album. This includes printing, exporting, exporting to web, and other.

A wide variety of zoom modes is available. You can also tweak some advanced options to make everything faster, paid off by a temporary decrease of the image quality

almara_album can also work with motion jpeg movies. The movie will be internally converted to a normal image album, and you will be able to work with it the same way you're used to with normal image albums. When you're ready with your movie, you can export it back to a motion jpeg. Of course, you can play the movie with an external player as well.

While working with almara_album, you won't even need to know..., but I'll tell you anyway: almara_album is just a frontend to almara_cht.

1.2.3 almara_cht, the hidden heart of Almara

A normal user does not interact with this module directly, almara_album will run it silently. Skip this section, if you're not interested in technical details.

almara_image itself can do almost no image operations. It only displays images. It does not even understand the album file. All the work, from reading and parsing the album file to scaling the image to the appropriate size for displaying, is done by almara_cht (CHT for short).

CHT receives requests from almara_album and tries to fulfill them. It runs a number of processes, so that more operations are performed in parallel. This will increase efficiency if you have a multiprocessor machine. To take full advantage of this, be sure to check the appropriate option in the almara_album config dialog.

Because generating the resulting image from the original may be a costly operation (the more logged operations, the slower), CHT tries to speed it up by maintaining a cache of pre-rendered images and by performing all the mid-way operations on a scaled-down version of the image. The cache is persistent (written on disk) and its size can also be set in the almara_album's configuration dialog. Likewise, the dimensions of the scaled_down image can be set in the same dialog.

Tweaking these settings may have large impact on the overall Almara speed, and on the quality of images you see. However, the original image stays untouched, and operations that export images to files or to other Almara modules always preserve the best achievable quality, so you can experiment at no risk.

1.2.4 Other Almara modules

Certain album operations are performed by external backend modules. almara_print_bin, for example, is called by CHT whenever you want to print. CHT will prepare all the images to be printed into a temporary location, and almara_print_bin will print them, after letting you chose printing options from its own graphical user interface.

almara_print_bin is a complicated program. On the contrary, the almara_webexport1_bin module is a Python script, straightforward to tweak to one's taste.

Other modules include mjpeg2jpegs and jpegs2mjpeg (which convert a motion jpeg movie into individual jpeg frames and vice versa) or almara_playmovie, which just calls jpegs2mjpeg and then mplayer. almara_playmovie will probably be the first backend you will want to modify if you don't like mplayer. Go ahead, it's not rocket science!

CHT also makes it easy to program frontends -- modules (usually scripts) that run their own copy of CHT, and use it to perform some operation with an album. almara_webexport is an example of such a frontend -- it allows you to quickly export an album to web, without the need of running the GUI modules. An experienced shell hacker will find it easy to base her own frontends on it.

The python script almara_mkalb is used for creating new albums from image directories. It is usually run from almara, but can also be run manually. almara uses it to create the album file witch some default names and descriptions and to scale the .welcome.jpg. Run almara_mkalb -h for command line options if you are interested in running the script manually.

2 Managing your albums with almara

2.1 Creating your first Almara album

Having run almara for the first time, you will want to go to the File menu, and open an album. Since you don't have any Almara albums yet, open a directory containing your images. almara will detect that there is no album (album.alb) file in the directory and will create one for you and launch almara_album

You may either skip to the chapter describing almara_album, or close the window that popped up and continue in the almara tour

You'll find that your new album has appeared in the "favorites" column, at the right side of the main window. The column shows the most important properties of every album. More detailed information about the currently selected album can be found near the bottom of the almara window. The remaining portion of the window shows the album name and a preview (thumbnails) of its images.

The thumbnails are not explicitly rendered for this purpose. Instead, cached thumbnails created by CHT and almara_album are re-used. If there are no thumbnails in the cache, no thumbnails will be shown. This might seem inconvenient, but creates no overhead, and allows you to browse the albums really fast.

2.2 What has been created?

What exactly has been created in your filesystem? -- Apart from an unspecified amount of temporary files under /tmp:

Your data will be kept untouched unless you perform a "commit" or similar operation in almara_album or explicitly tell almara to delete the album. In either case, you will be asked for confirmation. New images may be added to your directory by copy'n'paste in almara_album.

2.3 Menu tree

2.3.1 The File menu

You've seen already what the Open new album/directory item does. The Open movie item will let you open a motion jpeg movie. almara_album will be run and automatically convert the movie into an album.

Recent albums lists the last few albums you've opened. Quit will close the program.

2.3.2 The Search menu

The Find function will let you search your albums by their title, description or other data. A dialog box will appear. You can select the fields that will be searched, and specify a regular expression to be used for searching.

If you've never used regular expressions before, try to get the idea in the manual page of grep (type man grep in a shell prompt)

You can check the box next to User information to search in user defined fields. All fields matching the regular expression Which will be searched

The Find next item will repeat the last search to find further matches.

2.3.3 The Album menu

Everything in this menu relates to the currently selected album. Open and Open over will open the currently selected album in almara_album. The latter will close the current window, and re-open it when almara_album finishes. Use this if you don't like unnecessary windows cluttering up the screen.

Delete will erase the whole album directory, including the originals

Remove from favorites will only remove the album from the list and not how it again, until you add it again manually

Edit album header will allow you to change the title, description, and other album data. You can add more user defined strings by using the Add button. This may be useful e.g. for searching the album.

2.4 Other controls

2.4.1 Sorting the album list

The album list can be sorted by clicking on the column headers. Clicking the header of the Album view column will sort by album path. The sorting function of the other column may be changed by right-clicking in the column

2.4.2 Other

Double clicking the album in the "favorites" column will open it with almara_album. Double clicking of the album details will open the Edit album header dialog.

3 Viewing and editing images with almara_album

The almara_album window layout is similar to the one of almara, but richer and more configurable.

Let's call the narrow column on the left, containing image previews (thumbnails), the "image list". I'll call the bottom area, the one that shows image details, the "exif widget". The remaining portion of the window is occupied by the "image area". Down by the edge of the window is a "statusbar" that shows information concerning whatever is going on at the moment. On the right side of the statusbar is a "progressbar". The "toolbar" is just under the menus, and has buttons on it.

Almara behaves slightly different from other GTK+ based programs: we tried hard to maintain consistent keyboard behaviour throughout the main window, independent of which widget has been clicked or used last. The result takes some getting used to, but we believe that in the end it will be appreciated by most users. Special keys have been defined for all the operations you need to do, you can find (and modify!) them in the menu.

Talking about keyboard shortcuts - GTK has an option of allowing the user to configure her keyboard shortcuts at runtime by simply going to the corresponding menu item and pressing a key or a key combination. Some items in Almara menus are only there so that you can easily find out what shortcut keys there are, and modify them if you want to. This option has to be turned on by each user, either by putting gtk-can-change-accels = 1 in a file called .gtkrc-2.0 in her home directory or, if using GNOME, by setting /desktop/gnome/interface/can_change_accels in gconf-editor.

3.1 The image list

When almara_album starts, the image list will show all the images in the album. At first, only the filenames and descriptions will be shown. Thumbnails will start to appear shortly, as they are rendered.

Choosing an image in the image list will show it in the image area. You can jump to the next image by pressing space and to the previous by pressing backspace (can be set to down and up arrows respectively, using the configuration dialog). Other navigation keys can be found in the Scroll and Navigation menus

Images in the image list can also be "selected". Selected images will be marked by red colour and most image operations, explained later, will work with all selected images instead of the current image if you select any. Selecting can be done through the Edit menu. The Select group and Unselect group items will show a dialog. You can enter regular expressions to match the image's filename, description and keywords against. An image must match all three regular expressions to be selected/unselected. Alternatively, you can select by right-clicking the corresponding row.

You can also change the order of the images in your album (which is very handy when you edit a motion jpeg) using the image list. Select the images you want to put to a certain position, place the cursor to that position and do Edit|Move selected here.

By clicking on the Thumb column header, you invert the sorting order. Alternatively, you can sort by filenames or descriptions by clicking the other column's header.

Anyone used to Pine's "Zoom" feature will know what Edit|Focus in does: it will hide all the images that are not selected. Only the images that were selected will remain in the image list and will be unselected. Focuses can be nested, so you can narrow the number of images in the image list repeatedly. The current number of nested focuses will be shown in the statusbar. Edit|Focus out will cancel the innermost focus and will re-select the images that were visible in the focus, thus laving the selection in the state before the focus.

3.2 The exif widget

Most digital cameras add a header to every image they produce, containing lots of information about the image, the camera, the exposure settings, the lighting conditions and so on -- it's called the exif header. Mixed with certain values you may supply, e.g. description or keywords, we get what we call "image's metadata."

The exif widget lets you browse the metadata, and edit the user editable parts of it.

All operations you can do on the exif widget are accessible from the Exif menu. Because the number of exif fields can be very large and displaying them all would make widget hard to read, you can select only a few that will be displayed: First make them all appear by clicking on the leftmost column header. Then select the fields of interest, and click the leftmost column header again. All the fields you have not checked will be hidden. You can edit the user changeable fields by selecting Exif|Edit, or you can edit all editable fields at once by selecting the Exif|Edit step by step

3.3 The image area

The image area shows the image chosen in the image list. The way the image gets displayed is influenced by many factors, including:

3.3.1 Zoom modes

You can find a wide range of zoom modes in the View menu. The Fit to window modes adapt the zoom factor automatically, so that the image fits inside the image area. The Fit to window - conservative only adapts the zoom factor if it would substantially differ from one. Because zooming distorts the image, this preserves better quality in cases where the image size only slightly differs from the image area size. Fit to window - larger only never enlarges images. It only makes large images fit into smaller image areas.

3.3.2 Histograms

Almara can show a histogram for every image it displays. In Options|Widgets|Histograms, you can enable or disable the histograms, and select the channels you want the histograms for. Linear or logarithmic variants are available.

All histograms are composed into a single semi-transparent rectangle, that will be shown over the image. You can move the position of this rectangle using the same menu. Of course, showing histograms adds some overhead, so you'd better turn them off when you don't need them.

3.4 Image operations

Image operations work on individual images. If any image is selected, image operations will work on all selected images. If no image is selected, image operations will only affect the current image. Image operations can be found in the image and sound menus. Images can have an attached sound, and the sound menu performs operations on these sounds.

3.4.1 Simple image operations

The Image menu contains many well-known image operations and transforms. By "simple" I meant that they don't require any special parameters:

One thing you should keep in mind: Almara tries its best to do any requested operation on a jpeg image losslessly, even when that means minor inaccuracies. Attempted lossless operations include: rotation, crop and flip. Sometimes, requested operation's dimensions/coordinates are rounded to allow for the lossless version of the operation. Once an image has been modified by any lossy operation, no further lossless operations will be attempted.

3.4.2 Brightness/saturation/hue

a.k.a. modulate - lets you change the brightness, saturation and hue of an image. Selecting this, you will get a dialog with three sliders, modifying the individual values. You can check the Preview on current image checkbox, to see a preview. You will always see the preview on the chosen image, even in the case the operation will perform on all selected images.

Pressing Reset will return to the state when the dialog popped up. Pressing Cancel will ignore any changes and close the dialog. OK will apply the changes and close the dialog.

3.4.3 Scale

Almara's scale is really powerful, and lets you scale in three basic modes:

Advanced users may want to chose a specific scale algorithm, and supply a custom Blur parameter. Blur is a factor that will multiply the default, algorithm specific, radius around a filtered pixel. Setting blur to more than one will blur the image, while setting it to less than one will sharpen the image.

3.4.4 Irreversible operations

As stated before, most operations will only be logged into the album file, and the original will be kept untouched. As always, there are exceptions to the rule... a couple operations cannot be undone, and the originals are modified:

3.4.5 Exporting operations

Print, Export and Export to web are all exporting operations. They perform all the logged operations on the image, but unlike Commit, they don't modify the original. Instead:

Exporting the images may take quite some time. A small window with a progressbar will pop up, and the operation can always be aborted by selecting the Cancel button in the window.

Naturally, unlike other operations, printing and exporting to web will yield different results when done on a group of images at once and when doing it repeatedly for parts of the group -- the backends work with all the images they get as a whole.

3.4.6 Cropping and panning

Almara comes with advanced cropping features. They are all controlled with the mouse.

When no selection is active, clicking and dragging the right button will pan (scroll) the image. You can select from two panning modes. A GIMP-like mode is default (dragging the image over the screen); by pressing CTRL, you can switch to the reversed (GV-like) mode.

Left-click with no drag will jump to the next image. Right-click with no drag will jump to the the previous image.

3.5 Album operations

Album operations can be found in the Album menu and always work on the whole album, regardless what image is chosen, or whether any images are selected.

The Commit, Export,Export to web and Print items will do the same as their counterparts in the Image menu, but on every image in the album.

Save is not really important, as the album is automatically saved on close, and also in a user defined time interval. This is further explained in the "Configuration dialog" section.

3.5.1 Repeating and undoing operations

Whenever you do one of the above image operations, Almara will remember what it was, and what the parameters were. You can then repeat the operation by selecting Image|Repeat last operation. The operation will be repeated, with the original parameters, but acting on the currently selected or chosen image(s). Repeating an album operation will perform on the whole album, however.

There is also an Undo menu. This allows undoing any number of operations performed on the album since almara_album was started. When undoing more than one operation at a time, you will be asked for confirmation.

3.6 Movie operations

almara_album will automatically detect that it is working with a movie, and display some extra items in the Image and Album menus.

Play movie will appear both in the Image and in the Album menus. It will compose a movie file from the individual images and play it through the almara_playmovie backend.

An Export movie item will appear in the album menu; this prompts for a filename for the new movie to be saved in. If you select an existing movie (and confirm), the original will be lost.

3.7 Copy and paste

Almara comes with a clipboard copy and paste function. You can copy an image, or selected images, to the clipboard using Edit|Copy. Doing Edit|Paste will paste the contents of the clipboard to the current album. This works both within the current album and between more running instances of almara_album.

By pasting an image to the album, the original image from the source album is copied, as well as the operation log of the picture. Thus, by copying images through the clipboard, you don't lose image quality. This is also a simple way of adding new pictures to an existing album -- simply open the directory with the images you want to add with Almara, and use copy and paste.

3.8 The progressbar

You may be wondering how long you will have to wait before you see what you've done, or what exactly it is eating up all your CPU time at the moment. Let's have a look at the progressbar, located on the right of the statusbar.

By now, you should know that image operations are internally performed by almara_cht which runs a number of processes. More than one operation may be processed at the same time. Also, operations may be queued if CHT is too busy. Because some operations are more important than others, they are given priorities. CHT's internal scheduler does its best to first finish operations with greater priorities, while leaving lower-priority requests to be processed later.

The most important requests are those that are necessary to show the selected image. If any of those is pending, you will see their progress in red.

Almara pre-renders the images following and preceding the chosen image. As a result, when you go to the previous or next image, you won't have to wait that long. Rendering of these images is run at the second highest priority, and the progress of these requests is marked in green. You will see this progress if all "red-progress" requests are done.

Rendering thumbnails is done at even a lower priority. Their progress is shown in blue, and you will see it if no "red-progress" or "green-progress" requests are pending.

Occasionally, you will see a yellow progressbar. This shows requests, whose result will probably not be needed any time soon, but once they were started, we'll let them finish.

Progressbars that show when printing, exporting, committing or doing similar operations will be displayed in a separate window (which will allow for cancelling the operation) and are independent of the main progressbar.

3.9 The configuration dialog

When you select Options|Configuration, a configuration dialog will appear, that will let you configure several global options of almara_album. All these settings will be saved and loaded automatically on every program startup.

3.9.1 Autosave interval

As described before, instead of modifying the original images, Almara logs operations in what is called an "album file". While working with an album, all this information is stored internally in almara_cht's memory. "Saving the album" means dumping all this information to the appropriate album file. This is done:

3.9.2 Resolution of previewed image

Selecting this too small will speed up things a lot, but the images will be viewed in very poor quality. Setting it larger than your largest images will result in best quality viewing. See the explanation in the chapter about almara_cht for further details.

Users with slow machines will want to set the resolution low, and only see images in full quality when they explicitly request that. This is what the View|This image in full quality menu item will do. This will re-render the image bypassing almara_cht's optimizations and caches. If the image is a jpeg and any operation requiring decompression has been performed on the image, the image will be re-encoded and re-decoded to/from the jpeg format, so that the result will correspond to the real achievable quality. This operation is therefore slow. In the View menu, you can also toggle the Full quality option. This will render every image in the full quality described above. This will bypass important optimizations and will severely impact the performance. If you find almara_album unresponsive, please check that this option has not been turned on by accident.

3.9.3 Cache and scheduler policy

This is also explained in greater detail in the almara_cht chapter. Setting the cache larger will make Almara faster, because results of some image operations will be cached. The cache is located under the /tmp directory, so it might also be cleaned by system maintenance scripts or by the administrator

3.9.4 Arrows behaviour and wrapping over the image list

Using these settings you can set whether the arrow keys are used for panning (scrolling) the image, or whether they are used to navigate in the image list. You can also select whether falling off the bottom of the image list will get you back to the top and vice versa, or whether the cursor will stay on the first/last image.

3.10 The Display dialog

Theoretically, setting the correct gamma correction should not be left upon applications - it should be performed by the X server. In practice, however, people often don't bother to set it up properly, or they are not allowed to. Because correct gamma setting is crucial for good image viewing experience, Almara can perform gamma correction on all images being shown on the display. Go to Options|Display and either key in the values manually, or click on Wizard and a sequence of dialogs will guide you through setting the correct values.

3.11 Widget docking

Most of the main window's widgets can be either hidden, docked or floated. A docked widget will appear inside the main window. The size allocated to the image list, image area and exif widget can be set by dragging the separator between the widgets.

Hidden widgets don't appear at all. Hiding the widgets gives you more space for the image. Once you get used to all the keyboard shortcuts, you might want to hide the toolbar for example. On the other hand, if you only want to quickly skim through your album (perhaps while editing a movie) you might want to hide the image area. This will prevent rendering of images, and will significantly relieve the CPU load.

Widgets can also be floated. This means, that the widget will appear in its own toplevel window, and your window manager will define its behaviour. As almara does not support fullscreen viewing yet, you can easily use this feature instead -- most window managers can do fullscreen on any window, so you can float the image and then use your window manager's fullscreen feature.

Go to Options|Widgets and set everything according to your taste. The statusbar can only be shown or hidden -- not floated. You can use the Float all and Dock all items to quickly change the settings for all widgets at once.

3.12 Configuration files

All the settings in the config dialog, your widgets' layout, size and docking state, export quality and format, and many more options are saved in the .almara/almara_album.conf file in your home directory.

Feel free to modify this file. It is well commented, so it should be easy to edit. Deleting the file will make almara_album start with reasonable defaults.

Manual editing of the configuration file is the only way you can change the external image and sound editors and sound players.

The keyboard accelerators that you can modify at run time are stored in .almara/accelerators. Exif widget's settings are saved in .almara/exif_widget.conf. You can also edit or delete these files.

4 Printing with almara_print

almara_print is a small application for printing images. almara_print_bin is an Almara compatible backend, that uses almara_print to do its work. almara_print_bin will be run automatically each time you will print images from almara_album.

You can use almara_print independently of all other Almara modules. You can give it a list of image files on the command line, and they don't even need to be part of an album.

almara_print is based on the gnomeprintui library. Its user interface is basically just one complicated dialog with multiple tabs. All of them, except the Layout tab, come from gnomeprintui. See the gnomeprintui documentation for details.

4.1 The Layout tab

The Layout tab lets you specify the number of images per page, their borders and page margins. Selecting Autorotate photos to best fit will allow almara_print to rotate the images to minimize empty space on the page. Stretch photos to best fit will change the images' aspect ratio to fill all the available space.

Each image can have a white padding around it. You can specify its width in Photo padding. You can also specify the page margins.

almara_print can also print some of the metadata with each image. In the right half of the tab, you can select the information you want to print, specify the text position relative to each picture, and choose the font to be used.

All the settings can be saved to .almara/almara_print.conf using the Save config button.

5 Getting and installing Almara

For up-to-date instructions, please visit Almara's home page at http://almara.sourceforge.net/ and look for the INSTALL file.

A copy of this file, valid at the time of writing this guide, is attached as an appendix.

6 Epilogue

We hope you (will) enjoy using Almara. Your feedback, sane suggestions, and bugfixes will be greatly appreciated.

Those interested in writing new backends and frontends or in helping with the development are advised to read the Programmer's Guide, which describes Almara's internals in greated detail

The Almara team, 2003 - 2005, http://almara.sourceforge.net/