What is apophnia

Apophnia is a dedicated image server protocol. This is designed to solve all of the common image serving problems that are a pain to deal with for anyone that has to deal with a lot of images.

This is not intended to serve HTML, CSS, JAVASCRIPT, or any other kind of document. It just serves images.

Image Serving Problems

Various sizes of images are needed for various purposes.
Various miscellaneous transformations of images are needed for special purposes.
Image serving must be fast. An ideal web page will probably serve dozens of images, even with 1 compacted html file.
Images should have their own caching rules because how they change is different from the text content.
Images need to be dealt with in a way that doesn't break file systems because of their massive volume.
Images should have restful URLs to be saved to disk easily and ready for SEO.

What apophnia tries to achieve:

Be able to use new resolutions on the fly.
Have these dynamically created images cached.
Incur at most a one-time overhead in the process.
Have a dedicated image web server or a web server module to do it.

What an apophnia request looks like

Look for myimage_r500x500.jpg.
If not found, back up, try myimage.jpg
See that (_r500x500) is a resize directive
Dynamically resize myimage.jpg to 500x500, serve that image
Save a new file to disk myimage_r500x500.jpg so that when it is requested again ... it's easy

Directives

Supported Directives

RESIZE r[HEIGHT(xWIDTH)] example myfile_r1000x800.jpg myfile_r400.jpg (creates a 400x400)
OFFSET o[HEIGHTxWIDTH [ [p|m] VERTICAL ( [p|m] HORIZONTAL) ] Note the syntax is "p" and "m", not "+" and "-" because of HTML escape sequences example myfile_o100x100p100p50.jpg myfile_o400x400m10m40.jpg. It mattes white.
QUALITY qINTERGER (0 lowest, 99 highest) example myfile_q60.png myfile_q54.jpg
NOP _ example myfile________q60.png myfile__q54.jpg
FORMAT if x is specified and doesn't exist, then seek out other images in the order of y
GIF: png, bmp, jpg, jpeg, fail
JPG: jpeg, png, bmp, gif, tga, tiff, fail
PNG: gif, bmp, jpg, jpeg, tiff, fail
JPEG: jpg, png, bmp, gif, tga, tiff, fail
BMP: png, jpg, gif, jpeg, fail BMP Note: DIB v.5 (Win98/2K+) "supports BMP being a container format for both PNG and JPEG images":http://en.wikipedia.org/wiki/BMP_file_format#Bitmap_Information_.28DIB_header.29 and still being a valid BMP. Since JPEG has no alpha channel and BMP's alpha channel is the same engine as PNG's in IE 6, when a BMP is requested it will be a v.5 DIB encapsulated PNG to preserve the space, unless otherwise specified by the true_bmp configuration option.

Proposed Directives

Notes

h4. Chaining

Directives can of course be chained. If you have a file, say, a 2000x2000 file, myfile.bmp then you can do myfile_r1000x1000_o250x250p250p250_q50.png Here's the steps:

myfile_r1000x1000_o250x250p250p250_q50.png is sought out, fails. quality 50 is pushed on the stack. IOCount = 1
myfile_r1000x1000_o250x250p250p250.png fails. 250x250 at offset 250x250 is pushed on the stack. IOCount = 2
myfile_r1000x1000.png fails. resize as 1000x1000 is pushed on the stack. IOCount = 3
myfile.png fails. emit as png is flagged. IOCount = 4
myfile.gif fails ... myfile.bmp succeeds. IOCount = 5
myfile.bmp is opened. IOCount = 6
myfile.bmp is resized to 1000x1000
a 250x250 image is extracted at offset 250x250
it is encoded as png with an aggressiveness level of 4 (0-9 is png)
It is served to the client and asynchronously written to disk at myfile_r1000x1000_o250x250p250p250_q50.png IOCount = 7

As you can see, the first time the image is served, it is quite expensive. But now another client will request the same image: GET /myfile_r1000x1000_o250x250p250p250_q50.png HTTP/1.1

myfile_r1000x1000_o250x250p250p250_q50.png is sought out, found. Served to client.

Much better the second time around, eh?

Configuration File

The config file is called apophnia.conf and is in "JSON":http://www.json.org/ format.

Implementations

There is a protocol (discussed above) and implementations (discussed below). The following implementations exist:

C/ImageMagick/Mongoose

Implementations intend to achieve the following goals:

Manage the request to convert images
Convert source images to destination format
Cache images for future use
Update cache when necessary
Discard old images from cache

C Implementation

Supported Options

"port": INTEGER - default: 2345 The port to run apophnia on.
"img_root": STRING - default: "./" The root directory of images to serve
"proportion": ["squash", "crop", "matte", "seamcarve"] - default: squash. If a 200x1000 image is requested at 200x200, then you can either
squash: Squash the image disproportionally
crop: Center the content and crop the excess pixels
matte: Take the 200x1000 image, resize it to 40x200, center it, and matte it on a 200x200 white background
seamcarve: See the "wikipedia article":http://en.wikipedia.org/wiki/Seam_carving
"true_bmp:" INTEGER (0/1) - default: 0 Whether to serve a true, uncompressed bmp, or to encapsulate it in a DIB png
"log_level": [0 ... 3] - default: 0
0 - log only crashing conditions.
1 - log file creations and updates
2 - log all requests
3 - log as if it's not a performance hit
"log_file": STRING - default: /dev/stdout Where the log files go...
"404": STRING - default: empty The image to serve (if any) when no image is found.
"disk": BOOLEAN - default: 1 (true) Whether or not to write the converted files to disk

Proposed Options

"no_support": Array("DIRECTIVE1", "DIRECTIVE2") - default: empty/everything supported Example: To disable the quality and resizing directives, you can use "no_support": ["resize", "quality"]

kristopolous / apophnia