User guide

Problems with albums and images

    Thumbnails/sized images are not generated and/or the server crashes

    Server memory issues
    If you're running a web server on a VPS or other resource-limited environment, then you might not have enough memory available to the server to process very large images. You can use the following table as a guideline to see how much memory you need to process images of different sizes:
    • VGA Image, 640 x 480 pixels => needs ~4.1 MB Memory
    • SVGA Image, 800 x 600 pixels => needs ~4.8 MB Memory
    • 1 MP Image, 1024 x 798 pixels => needs ~6.3 MB Memory
    • 2 MP Image, 1600 x 1200 pixels => needs ~11.7 MB Memory
    • 6 MP Image, 2816 x 2112 pixels => needs ~22.6 MB Memory
    • 8.2 MP Image, 3571 x 2302 pixels => needs ~41.7 MB Memory
    As you can see, the 8.2-Megapixel 3571x2302 image requires a very large amount of memory to process, and that's simply because of the number of pixels. It doesn't matter if the image is only 2 or 3 megabytes when compressed in JPEG form, or what colors the image contains or anything-- it's just how big it is, because all of those pixels have to have a place in memory while the GD library processes them. There's no way around it!
     
    Zenphoto attempts to run the image processor in as small a memory footprint as possible. You should be aware, however, that some image option choices will increase that footprint. They provide useful features, but come at a cost. Options that force increased footprint are: Obscure Cache Filename, Protect Image Cache, Secure Image Processing, and IPTC Imbedding. Disabling these options may allow successful processing of images that fail to render because of memory limits.
     
    Workaround 1: Re-configuring your server to work with large image files (5MB to 10MB)

    Tutorial written by Aladio (https://github.com/zenphoto/zenphoto/issues/169)

    The aim of this tutorial is to help the intermediate user configure PHP and setup large image files so they may be uploaded and displayed properly using Zenphoto.

    Configuring PHP

    The following 5 settings need to be verified or changed in the php.ini file, found on your web server, in order to run Zenphoto with large image files.

    Note: You should confirm with your web-host that these settings are supported and how much server memory is available! If you are on a shared host you probably might not be allowed/able to changes these.

    1. Find memory_limit around line 455 set it to 128M
      ; Maximum amount of memory a script may consume (128MB)
      http://php.net/memory-limit
      memory_limit = 128M

    2. Find post_max_size around line 725 set it to a big number so you can upload multiple large files.
      ; Maximum size of POST data that PHP will accept.
      http://php.net/post-max-size
      post_max_size = 1G

    3. Find file_uploads around line 865 set it to On.
      ; Whether to allow HTTP file uploads.
      http://php.net/file-uploads
      file_uploads = On

    4. Find upload_max_filesize around line 865 set it to a big number so you can upload multiple large files.
      ; Maximum allowed size for uploaded files.
      http://php.net/upload-max-filesize
      upload_max_filesize = 1G

    5. Find max_file_uploads around line 865 set it to upload multiple files at once.
      ; Maximum number of files that can be uploaded via a single request
      max_file_uploads = 20

    Setting up Large Image Files (5MB to 10MB)

    Horizontal or Landscape Images (height < width)

    If you are able to make the above changes to your php.ini file, large landscape image files should display fine when running Zenphoto.

    Vertical or Portrait Images (height > width)

    Large portrait image files must be rotated properly or PHP will run out of memeory while Zenphoto is trying to rotate and resize your image. You will see a box containing the name of the image instead of the image itself if the error occurs. (See below for directions on how to debug images).

    Zenphoto reads the EXIF data contained in the image file to determine the image orientation. If the EXIF orientation property is set to anything but 1, Zenphoto will try to rotate your image. If the image is a large one the process will fail.

    Debugging images

    There could be many reasons for this, so the best way to diagnose this problem is to view the actual image error itself. You can do this by adding '&debug' to the image URL zenphoto uses to process the image.

    To do that, locate the failed image in your gallery (it should show just the filename with a box around it, in place of the image), then right-click it and choose 'Copy Image Location' (Firefox; in IE, choose 'properties' and copy the image URL from there).

    Then, paste that URL into your address bar, and at the end of it, type "&debug" without quotes. Press enter to see the image processor's error message. If you need help diagnosing it, feel free to post on the support forums.

    Workaround 2: Use Imagick instead of the GD libary

    Since Zenphoto 1.3 you can also switch to Imagick (ImageMagick) which may require less memory, and at least won't share memory with Apache. If your server supports this you can enable it via a checkbox on Options > Image.

    Browser connection issues

    Another problem is that browsers often make two requests per server at the same time to speed up image loading. This is perfectly normal, but if two requests for that 8-megapixel image are made and both need processing, then the memory requirement is doubled. The only way around this is to limit the number of requests your browser makes. In Firefox, this can be done by going to about:config as the URL and searching for the network.http.max-persistent-connections-per-server option and setting it to 1.

    Corrupt image files

    Sometimes the cause can also be a corrupte image file. That can happen sometimes if you upload via FTP or a general program error. Try opening the file with an editor and re-saving it.

    Corrupt EXIF/meta data

    If you are using EXIF or IPTC meta data this data can be corrupted. That can happen if your editor or camera embeds it wrong or by encoding issues. Try to open the file with an editor and try to re-save it.

    Images have wrong colors

    First, most older web browsers ignore color profiles. Newer ones generally can. 

    Second, there are two aspects of color space. The first is the RGB values of the pixels. Then there is a color profile which may be associated with an image. So you can have pixels which are sRGB or adobeRGB or some other "color space". If the pixels are not sRGB then typically the web programs will not display the color correctly. If they are, then things should be fine.

    Zenphoto does resizing of images with image processing libaries that are installed on your server. Zenphoto supports two of them:

    1. GDlibary: This is the default libary which is most commonly availabe on servers. GD does NOT support or preserve color profiles embeded in images.
    2. Imagick libary (since 1.3): This is capable to preserve color profiles but the recommendation to use sRGB still persists.
    Also beware that the commonly used "export to web" feature of some well know image processing tools generally does strip meta data including color profiles from image to achieve smaller file sizes.

    The number of thumbnails on a theme's album view do not match theme settings

    When a theme specifies a setting for the number of image (or album) thumbnails to display in a "row", the thumbnails per page will be rounded up to the nearest multiple of that specification. Prior to the 1.3.2 release setting these were done via the normalizeColumns() function. Post 1.3.2 the settings are on the theme options tab.

    Deleting an albums fails on the backend

    This may be caused by some files within the folder of that album that should not be there like for example the hidden/invisible .DS_Store files the finder of Mac OS X creates. They may be transfered with upload folders or archives. You would have to delete these files directly via ftp. Best is to avoid uploading them in the first place.

    Thumbnails for videos (or other non standard image files) are not created

    Zenphoto is not able to generate thumbnails from videos and shows therefore a default replacement image. There is no way at all to do this automatically with PHP without installing a native extension on your server itself. But you can do it manually:

    • Make a screenshot from your movie
    • Put the image named as the movie (for example: movie named movie.mp4, image named movie.jpg — lower case suffixes are required!) into the album folder where your movie is located.

    Same principle works for all non image content used by plugins like audio files, text objects or file formats added by the anyFile plugin.

    Only for videos: If you run your own server and are able to install native PHP packages you might be able to setup ffmpeg to create thumbnails from videos. Our user wcroth55 wrote a short tutorial about that (scroll down to section IV):
    http://thedance.net/~roth/TECHBLOG/zenphoto.html

    Note: The thumb is determined by filename minus suffix. So if you have movie.m4v and movie.mp4 and an image movie.jpg both will get it as the thumb. Name your non-image files individually to avoid this.

    The image rotate button on the backend is grayed-out

    The GD graphics libary on your server is missing support for image rotation. You have to contact your host about that.

    Images are not displaying after installation

    There are a number of reasons why you photos might not display after installation and setup.

    1. You may need to check your permissions on your albums directory and cache directory. Permissions for Zenphoto files and folders
    2. It could be that PHP Safe Mode is enabled. Your ISP will need to help you with this configuration. 
    3. Check your .htaccess file if you're using Apache, and make sure you have the correct path for the RewriteBase line at the top. If you're not using Apache or it doesn't seem to be working, reset your mod_rewrite option.
    4. Search the ZenphotoForums for help, or start a new topic there. Zenphoto has a very helpful community, so don't be shy!

    Trouble with file/folder names containing accented characters

    It is best you avoid using accented characters in your file or folder names. It is really unnecessary to use them in file/folder names since you can edit the title to use whatever characters you like. Your site viewers see the title, not the file/folder name.

    The technical explaination is that Zenphoto stores its data in UTF-8 format in the database. But your files ystem probably uses some other character set, most likely ISO-8859-1. So when Zenphoto gets the name of the image (filename) or the album (folder name) the character set of that string will not be UTF-8. This is OK as long as the string also does not contain any characters which are invalid in UTF-8. Unfortunately many accented characters from ISO-8859-1 are not valid when interpreted in UTF-8 so when the string is stored into the database MySQL truncates it at the first non UTF-8 character.

    Current versions of Zenphoto will handle conversion of file system character strings to UTF-8 representation. However Zenphoto assumes that the filesystem characterset is ISO-8859-1, so if yours is in some other character set, things still will not work. Another player in this drama is the character set assumed for image URIs. Most servers seem to use ISO-859-1 even though the page claims to be in UTF-8. If your server actually assumes UTF-8 for these, you need to change the UTF8 image URIs option on the gallary configuration tab.

    The images are in /zenphoto/albums/Myalbum but the URL says /zenphoto/Myalbum

    The URLs are correct as Zenphoto makes them. They aren't supposed to have albums in them because they aren't pointing to the folder! They're rewritten by the Apache module mod_rewrite, which translates URLs into script arguments, in this case, inputs to Zenphoto. Read the next question to find out how this works.

    Opening full images in Colorbox or another overlay script does not work

    If you see some weird messy text showing instead of the full image you need to disable the full image protection on the backend options (Options > Images > Full Image Protection). These "box" scripts need to access the full image directly which naturally is not possible if it is protected.

    Embedded images in Zenpage articles or pages are broken

    To avoid overhead, embedded images are converted to direct links to cached images instead of the i.php image processor urls. If you clear the cache those naturally are broken afterwards.

    To repair those enable the cacheManager plugin and access its button "cache images" on the admin overview page. Then access the tab "cache stored images".

    The "albums" on the front- and/or backend are slow

    Additionally to the reasons above: If you have lots of albums and subalbums with lots of images the reason could be the "album thumbnail". That is the thumbnail that represents an albums. What you can try:

    • Disable the automatic thumbnail selection and set it to a fixed image. You can do this on each album or globally on the gallery options. Otherwise Zenphoto will randomly choose one from all images within this album including subalbums. Since it has to process uncached images this slows down depending on the size of the image. 
    • Disable the option "gallery > visual thumb selection" and "gallery > subalbum thumb selection". Both are normally off by default.
    • On the image pages you can choose how many images to show per page and speed up its loading.

     All this is related to caching the resized images.

    Creative Commons LicenseThis text by www.zenphoto.org is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.

    For questions and comments please use the forum or discuss on the social networks.