MarginalHacks album - Running album / Basic Options - Documentation

| A l b u m T h r e e - - R u n n i n g a l b u m / B a s i c O p t i o n s

### Home
### Themes/Examples
### Languages
### Plugins
### License
### Download
### Documentation English Deutsch Español Français Nederlands Русский Italiano magyar
### Mailing List
### CHANGELOG
### Praises
### Contact
| Table Of Contents Basic execution Options Themes Sub-albums Avoiding Thumbnail Regeneration Cleaning Out The Thumbnails Medium size images Captions EXIF Captions Headers and Footers Hiding Files/Directories Cropping Images Video Burning CDs (using file://) Indexing your entire album Updating Albums With CGI
    1:   Basic execution

    Create a directory with nothing but images in it.  The album script and
    other tools should not go here.  Then run album specifying that directory:

    % album /example/path/to/images/

    Or, if you're in the /example/path/to directory:

    % album images/

    When it's done, you'll have a photo album inside that directory starting
    with images/index.html.

    If that path is in your web server, then you can view it with your
    browser.  If you can't find it, talk to your sysadmin.

    2:   Options
    There are three types of options.  Boolean options, string/num options
    and array options.  Boolean options can be turned off by prepending -no_:

    % album -no_image_pages

    String and number values are specified after a string option:

    % album -type gif
    % album -columns 5

    Array options can be specified two ways, with one argument at a time:

    % album -exif hi -exif there

    Or multiple arguments using the '--' form:

    % album --exif hi there --

    You can remove specific array options with -no_<option>
    and clear all the array options with -clear_<option>.
    To clear out array options (say, from the previous album run):

    % album -clear_exif -exif "new exif"

    (The -clear_exif will clear any previous exif settings and then the
     following -exif option will add a new exif comment)

    And finally, you can remove specific array options with 'no_':

    % album -no_exif hi

    Which could remove the 'hi' exif value and leave the 'there' value intact.

    Also see the section on Saving Options.

    To see a brief usage:

    % album -h

    To see more options:

    % album -more

    And even more full list of options:

    % album -usage=2

    You can specify numbers higher than 2 to see even more options (up to about 100)

    Plugins can also have options with their own usage.

    3:   Themes

    Themes are an essential part of what makes album compelling.
    You can customize the look of your photo album by downloading a
    theme from MarginalHacks or even writing your own theme to match
    your website.

    To use a theme, download the theme .tar or .zip and unpack it.

    Themes are found according to the -theme_path setting, which is
    a list of places to look for themes.  Those paths need to be somewhere
    under the top of your web directory, but not inside a photo album
    directory.  It needs to be accessible from a web browser.

    You can either move the theme into one of the theme_paths that album
    is already using, or make a new one and specify it with the -theme_path
    option.  (-theme_path should point to the directory the theme is in,
    not the actual theme directory itself)

    Then call album with the -theme option, with or without -theme_path:

    % album -theme Dominatrix6 my_photos/
    % album -theme Dominatrix6 -theme_path /home/httpd/album/Themes/ my_photos/

    You can also create your own themes pretty easily, this is covered
    later in this documentation.

    4:   Sub-albums

    Make directories inside your first directory and put images in that.
    Run album again, and it will run through all the child directories
    and create sub-albums of the first album.

    If you make changes to just a sub-album, you can run album on that
    and it will keep track of all the parent links.

    If you don't want to traverse down the tree of directories, you
    can limit it with the depth option.  Example:

    % album images/ -depth 1

    Will only generate photo albums for the images directory.

    If you have many sub-albums, and you want to add a new sub-album
    without regenerating all the previous sub-albums, then you can use -add:

    % album -add images/new_album/

    Which will add the new_album to the HTML for 'images/' and then
    generate the thumbs and HTML for everything inside 'images/new_album/'

    5:   Avoiding Thumbnail Regeneration

    album tries to avoid unnecessary work.  It only creates thumbnails if
    they don't exist and haven't changed.  This speeds up successive runs
    of album.

    This can cause a problem if you change the size or cropping of your
    thumbnails, because album won't realize that the thumbnails have changed.
    You can use the force option to force album to regenerate thumbnails:

    % album -force images/

    But you shouldn't need to use -force every time.

    6:   Cleaning Out The Thumbnails

    If you remove images from an album then you'll have leftover thumbs and HTML.
    You can remove them by running album once with the -clean option:

    % album -clean images/

    7:   Medium size images

    When you click on an album thumbnail you're taken to an 'image_page.'
    The image_page shows, by default, the full size image (as well as
    navigation buttons and captions and such).  When you click on the
    image on the image_page, you'll be taken to the URL for just the full
    size image.

    If you want a medium size image on the image_page, use the -medium
    option and specify a geometry for the medium size image.  You can
    specify any geometry that ImageMagick can use (see their man page
    for more info).  Some examples:

    # An image that is half the full size
    % album -medium 50%

    # An image that fits inside 640x480 (maximum size)
    % album -medium 640x480

    # An image that is shrunk to fit inside 640x480
    # (but won't be enlarged if it's smaller than 640x480)
    % album -medium '640x480>'

    You need the 'quotes' on the last example with most shells because
    of the '>' character.

    8:   Captions

    Images and thumbnails can have names and captions.  There are a number
    of ways to specify/change names and captions in your photo albums.

    The name is linked to the image or image_page,
    and the caption follows underneath.

    The default name is the filename cleaned up:
      "Kodi_Cow.gif"  =>  "Kodi Cow"

    One way to specify a caption is in a .txt file
    with the same name as the image.  For this example,
    "Kodi_Cow.txt" could contain "Kodi takes down a cow!"

    You can rename your images and specify captions in bulk
    for an album directory with a captions.txt file.

    Each line of the file should be an image or directory filename,
    followed by a tab, followed by the new name.  You can also
    specify (separated by tabs), an optional caption and then an optional
    image ALT tag.  (To skip a field, use 'tab' 'space' 'tab')

    Example:

    001.gif	My first photo
    002.gif	Mom and Dad My parents in the grand canyon
    003.gif	Ani DiFranco	My fiancee	Yowsers!

    The images and directories will also be sorted in the order they are found
    in the caption file.  You can override this with '-sort date' and '-sort name'

    If your editor doesn't handle tabs very well, then you can separate the
    fields by double-colons, but only if the caption line doesn't contain any
    tabs at all:

    003.gif :: Ani DiFranco :: My fiancee :: Yowsers!

    If you only want captions on image pages (not on album pages) use:

    % album -no_album_captions

    If you want web access to create/edit your captions, look at the
    caption_edit.cgi CGI script (but be sure to limit access to the
    script or anyone can change your captions!)

    9:   EXIF Captions

    You can also specify captions that are based off of EXIF information
    (Exchangeable Image File Format) which most digital cameras add to images.

    First you need 'jhead' installed.  You should be able to run jhead
    on a JPG file and see the comments and information.

    EXIF captions are added after the normal captions and are specified with -exif:

    % album -exif "<br>File: %File name% taken with %Camera make%"

    Any %tags% found will be replaced with EXIF information.  If any %tags%
    aren't found in the EXIF information, then that EXIF caption string is
    thrown out.  Because of this you can specify multiple -exif strings:

    % album -exif "<br>File: %File name% " -exif "taken with %Camera make%"

    This way if the 'Camera make' isn't found you can still get the 'File name'
    caption.

    Like any of the array style options you can use --exif as well:

    % album --exif "<br>File: %File name% " "taken with %Camera make%" --

    Note that, as above, you can include HTML in your EXIF tags:

    % album -exif "<br>Aperture: %Aperture%"

    To see the possible EXIF tags (Resolution, Date/Time, Aperture, etc..)
    run a program like 'jhead' on an digital camera image.

    You can also specify EXIF captions only for album or image pages, see
    the -exif_album and -exif_image options.

    10:  Headers and Footers

    In each album directory you can have text files header.txt and footer.txt
    These will be copied verbatim into the header and footer of your album (if
    it's supported by the theme).

    11:  Hiding Files/Directories

    Any files that album does not recognize as image types are ignored.
    To display these files, use -no_known_images.  (-known_images is default)

    You can mark an image as a non-image by creating an empty file with
    the same name with .not_img added to the end.

    You can ignore a file completely by creating an empty file with
    the same name with .hide_album on the end.

    You can avoid running album on a directory (but still include it in your
    list of directories) by creating a file <dir>/.no_album

    You can ignore directories completely by creating a file <dir>/.hide_album

    The Windows version of album doesn't use dots for no_album, hide_album
    and not_img because it's difficult to create .files in Windows.

    12:  Cropping Images

    If your images are of a large variety of aspect ratios (i.e., other than
    just landscape/portrait) or if your theme only allows one orientation,
    then you can have your thumbnails cropped so they all fit the same geometry:

    % album -crop

    The default cropping is to crop the image to center.  If you don't
    like the centered-cropping method that the album uses to generate
    thumbnails, you can give directives to album to specify where to crop
    specific images.  Just change the filename of the image so it has a
    cropping directive before the filetype.  You can direct album to crop
    the image at the top, bottom, left or right.  As an example, let's
    say you have a portrait "Kodi.gif" that you want cropped on top for
    the thumbnail.  Rename the file to "Kodi.CROPtop.gif" and this will
    be done for you (you might want to -clean out the old thumbnail).
    The "CROP" string will be removed from the name that is printed in
    the HTML.

    The default geometry is 133x133.  This way landscape images will
    create 133x100 thumbnails and portrait images will create 100x133
    thumbnails.  If you are using cropping and you still want your
    thumbnails to have that digital photo aspect ratio, then try 133x100:

    % album -crop -geometry 133x100

    Remember that if you change the -crop or -geometry settings on a
    previously generated album, you will need to specify -force once
    to regenerate all your thumbnails.

    13:  Video

    album can generate snapshot thumbnails of many video formats if you
    install ffmpeg

    If you are running linux on an x86, then you can just grab the binary,
    otherwise get the whole package from ffmpeg.org (it's an easy install).

    14:  Burning CDs (using file://)

    If you are using album to burn CDs or you want to access your albums with
    file://, then you don't want album to assume "index.html" as the default
    index page since the browser probably won't.  Furthermore, if you use
    themes, you must use relative paths.  You can't use -theme_url because
    you don't know what the final URL will be.  On Windows the theme path
    could end up being "C:/Themes" or on UNIX or OSX it could be something
    like "/mnt/cd/Themes" - it all depends on where the CD is mounted.
    To deal with this, use the -burn option:

      % album -burn ...

    This requires that the paths from the album to the theme don't change.
    The best way to do this is take the top directory that you're going to
    burn and put the themes and the album in that directory, then specify
    the full path to the theme.  For example, create the directories:

      myISO/Photos/
      myISO/Themes/Blue

    Then you can run:

      % album -burn -theme myISO/Themes/Blue myISO/Photos

    Then you can make a CD image from the myISO directory (or higher).

    If you are using 'galbum' (the GUI front end) then you can't specify
    the full path to the theme, so you'll need to make sure that the version
    of the theme you want to burn is the first one found in the theme_path
    (which is likely based off the data_path).  In the above example you
    could add 'myISO' to the top of the data_path, and it should
    use the 'myISO/Themes/Blue' path for the Blue theme.

    You can also look at shellrun for windows users, you can have it
    automatically launch the album in a browser.  (Or see winopen)

    15:  Indexing your entire album
    To navigate an entire album on one page use the caption_index tool.
    It uses the same options as album (though it ignores many
    of them) so you can just replace your call to "album" with "caption_index"

    The output is the HTML for a full album index.

    See an example index
    for one of my example photo albums

    16:  Updating Albums With CGI

    First you need to be able to upload the photo to the album directory.
    I suggest using ftp for this.  You could also write a javascript that
    can upload files, if someone could show me how to do this I'd love to know.

    Then you need to be able to remotely run album.  To avoid abuse, I
    suggest setting up a CGI script that touches a file (or they can just
    ftp this file in), and then have a cron job that checks for that
    file every few minutes, and if it finds it it removes it and runs album.
    [unix only]  (You will probably need to set $PATH or use absolute paths
    in the script for convert)

    If you want immediate gratification, you can run album from a CGI script
    such as this one.

    If your photos are not owned by the webserver user, then you
    need to run through a setud script which you run from a CGI [unix only].
    Put the setuid script in a secure place, change it's ownership to be the
    same as the photos, and then run "chmod ug+s" on it.  Here are example
    setuid and CGI scripts.  Be sure to edit them.

    Also look at caption_edit.cgi which allows you (or others) to edit
    captions/names/headers/footers through the web.
Created by make_faq from Marginal Hacks

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |

         ^
         |