for Instant Picture Creator version 0.1

Configuration will be done in instantpicture.conf.php!

To work properly Instant Picture need to know where your filters and cache files are located. Please edit following lines:

# System Configuration --- Begin

$pathToCache = "./cache/"; // path to cache files, relative to location of instantpicture.php
$pathToFilters = "./filters/"; // path to filters, relative to location of instantpicture.php
 
# System Configuration --- End

If the directories cache and filters are in the same folder where instantpicture.php is located you don't need to edit this. It will work! Otherwise Instant Picture Creator needs to know that places relative to his own location. Example:

• location of instantpicture.php: /path/to/InstantPicture/instantpicture.php
• location of cache files: /otherpath/to/imagecache/
• location of filter: /path/to/InstantPicture/

That example causes following changes:

# System Configuration --- Begin

$pathToCache = "./../../../otherpath/to/imagecache/"; // path to cache files, relative to location of instantpicture.php
$pathToFilters = "./"; // path to filters, relative to location of instantpicture.php
 
# System Configuration --- End

The ending slash (/) is needed!

Search and edit in instantpicture.conf.php following lines:

# User Preferences --- Begin

$quality = 80; // quality for Jpeg images: 1 (worst) to 99 (best)
$debug = 1; // debug level: 0 (off) | 1 (on, showed in picture) | 2 (debuginfo)
$debugtype = 'png'; // image type for debug info
$cache = 'off'; // off | hash | long | mixed
$cachefilterorder = false; // order of requested filters belongs to cache name
$defaultfilter = 'nofilter'; // default filter used for images requested without filter
 
// shortcuts for filters and combined filters
# $shortcuts['shortcut'] = 'anothershortcut01/anothershortcut02';
# $shortcuts['anothershortcut01'] = 'filter1-attr1-attr2';
# $shortcuts['anothershortcut02'] = 'filter2-attr1/filter3-attr1-attr2-attr3';

# User Preferences --- End

• $quality needs a integer value between 0 and 100, I would suggest values between 70 and 90
• $debug defines the debug level, it's important when errors occur. Possible values are:
  • 0: debug feature is off, Instant Picture will return a 404 error (document not found) when errors occur. I suggest to use this when it seems that Instant Picture works correct.
  • 1: debugging is on, Instant Picture will show all errors in the picture. It's good to see errors while Instant Picture is integrated with your website.
  • 2: system info, it will show some intern vars of Instant Image in a picture. So you can check if the core functions working well. Maybe you need this when debuglevel 1 shows some strange errors or when you develop your own filters.
• $cache is to switch caching on and it defines name convention for cached images:
  • 'off': filtered images won't be cached. Use this only while integration with your website! To filter an image again and again will need a lot of server time and power. Your server will get very slow (and maybe instable too)
  • 'hash': use a unique md5 hash string as image's cache name, you cannot relate a cache name back to to image (when you need)
  • 'long': creates a cache name out of image's name, directory and used filter. Example: http://server.com/path/to/image/imagename-01.jpg?filter=Resize-max-500/Palette-grey becomes path_to_image_imagename-01_jpg_resize-max-500_palette-grey. This is very clear but can lead to very long cache names and maybe it causes server errors.
  • 'mixed': will create cache name like image-01_jpg_[md5-hash-for-path-and-filters]. I suggest this because it's a good compromise between the problems with 'hash' and 'long'!
  • For caching filtered images the cache folder have to be writeable! Otherwise it will occur an error.
• $cachefilterorder defines if filters' order causes cache name or not
  • true: ?filter=Resize/Palette and ?filter=Palette/Resize will have different names for their cache files
  • false: combination of same filters will lead to one cache name, no matter of different sequences. I suggest to us this!
• $defaultfilter: Instant Picture will use this for every image request without filters
  • can be a valid filter (or combination, or shortcuts) or the $nofiltername value
  • Example: with $defaultfilter='Greyscale' a request for http://server.net/image.png leads intern to http://server.net/image.png?filter=Greyscale

Usually filter and its attributes will be a long string like Resize-max-100 (resize image to 100 pixels for the longer side) or Palette-gray-32 (changing colours to greyscale with 32 tones), the combination Resize-max-100/Palette-gray-32 is even longer. If you feel it looks not good or it is harder to work with then try it with shortcuts. Example:

// shortcuts for filters and combined filters
$shortcuts['Greythumb'] = 'Resize-max-100/Palette-gray-32';

or a little bit more modular:

// shortcuts for filters and combined filters
$shortcuts['Greythumb'] = 'Thumbnail/Grey32';
$shortcuts['Grey32'] = 'Palette-gray-32';
$shortcuts['Thumbnail'] = 'Resize-max-100';

Now a request for
http://server.net/image.png?filter=Greythumb
turns out like a request for
http://server.net/image.png?filter=Resize-max-100/Palette-gray-32.

The order of the shortcut sequence is very important. For the sample above following code won't work:

// shortcuts for filters and combined filters
$shortcuts['Grey32'] = 'Palette-gray-32';
$shortcuts['Thumbnail'] = 'Resize-max-100';
$shortcuts['Greythumb'] = 'Thumbnail/Grey32';

This is a very important topic. It is strongly recommended to configure all security issues! Edit in instantpicture.conf.php:

# Security Configuration --- Begin

$nofiltername = 'nofilter'; // filter dummy name for unfiltered image
$nofilter = true; // is the filter dummy for unfiltered image allowed as filter in url
 
// array for all allowed filters, it's recommended to use that for security issues
// empty array: all requested filters will be used
// non-empty array: only that filters are allowed to be used
// $filtersallowed[] = 'filter-attr1-attr2';
 
# Security Configuration --- End

• $nofiltername is a string what will be used intern for images requested without any filter parameters. Beside that you can use it as filter to request a unfiltered image (like http://server.net/image.png?filter=nofilter). This could be important if you defined a special default filter.
• $nofilter is to restrict the use of http://server.net/image.png?filter=nofilter.
  • true: http://server.net/image.png?filter=nofilter will return the unfiltered image
  • false: http://server.net/image.png?filter=nofilter will return an image filtered by default filter. You may use this feature to protect your original images.

Please configure all allowed filters! Otherwise it would be very easy to put your server down. Imagine a request like http://server.net/image.png?filter=Resize-min-100000/Palette-bw-3 (resize picture to 100'000 pixels for shorter side and change colours to black-white by Bayer transformation). Some parallel requests like that and probably your server breaks down.

Example: if you only use Resize-dim-20000, Resize-square-200, Palette-gray-8 and Palette-bw-1 then please define

$filtersallowed[] = 'Resize-dim-20000';
$filtersallowed[] = 'Resize-square-200';
$filtersallowed[] = 'Palette-gray-8';
$filtersallowed[] = 'Palette-bw-1';

Now the example request http://server.net/image.png?filter=Resize-min-100000/Palette-bw-3 will return an error and Instant Picture don't start to filter the image.

Currently it's not possible to use place holders like in $filtersallowed[]='Resize-*-200' or $filtersallowed[]='Resize-max-?00'. Maybe I will implement it later.

• see also: Resize filter

You have to be allowed to use a .htaccess file in your server directories. Sometimes your provicer decide to use another name like .htprovider or this.is.the.conf. It could be every name. Please ask your provider how to use .htaccess files.

Instant Picture Creator comes with a prepared user.htaccess:

<FilesMatch "\.(gif|jpg|jpeg|png|GIF|JPG|JPEG|PNG)">
  <IfModule mod_rewrite.c>
    # try to use Apache's Rewrite module
    RewriteEngine on
    RewriteCond %{REQUEST_FILENAME} -f
    RewriteRule . /path/to/instantpicture.php?picture=%{REQUEST_URI}?%{QUERY_STRING}
  </IfModule>
  <IfModule !mod_rewrite.c>
  # Rewrite module is not available, fallback to AddType/AddHandler and Action
    <IfModule mod_mime.c>
      <IfModule mod_actions.c>
        AddType application/x-httpd-parse .jpg .JPG .jpeg .JPEG .gif .GIF .png .PNG
        #AddHandler application/x-httpd-parse .jpg .JPG .jpeg .JPEG .gif .GIF .png .PNG
        Action application/x-httpd-parse "/path/to/instantpicture.php?picture="
      </IfModule>
    </IfModule>
    <IfModule !mod_mime.c>
      # Rewrite and AddType/Action dont't work, fallback to Redirect (Apache's Alias module)
      <IfModule mod_alias.c>
        RedirectMatch temp "^(.*)$" http://yourserver.com/path/to/instantpicture.php$1
      </IfModule>
    </IfModule>
  </IfModule>
</FilesMatch>

Don't ask me why I checked for modules like Mime, Action and Alias first because usually they are activated in Apache by default. I just did :)

Anyway, the first line defines the image types which will be wrapped by Instant Picture. If you want to use it only for PNG images you should use:

<FilesMatch "\.(png|PNG)">

And so on … Default is set to use Instant Picture for all ordinary web image types like GIF, PNG and JPEG.

Then you must replace dummy location /path/to/instantpicture.php by the real location. Change also http://yourserver.com to the right name.

Now rename user.htaccess to .htaccess (or the name your provider wants) and copy it to your server. The place of .htaccess is direct related to how many pictures will be wrapped by Instant Image. If you put it to your web root directory then all pictures are affected. If you put it into /imagefolder/ only picture in /imagefolder/ and its sub directories will be affected. You may also copy it to different folders like /imagefolder01/ and /imagefolder02/public/.

Instant Picture Creator doesn't work? Do you have an approvement for that documentation? Any Problems with it? Please write to haschek@users.sourceforge.net or add your comment at freshmeat.