NAME

Image::JpegMinimal - create JPEG previews without headers

SYNOPSIS

    my $compressor = Image::JpegMinimal->new(
        xmax => 42,
        ymax => 42,
        jpegquality => 20,
    );

    sub gen_img {
        my @tags;
        for my $file (@_) {
            my $imager = Imager->new( file => $file );
            my $preview = $compressor->data_preview( $file );
            my ($w, $h ) = ($imager->getwidth,$imager->getheight);
        
            my $html = <<HTML;
    <img width="${w}px" height="${h}px"
       data-preview="$preview"
       src="$file"
       />
    HTML
            push @tags, $html;
        };
        
        return @tags
    }

    # This goes into your HTML
    print join "\n", gen_img(@ARGV);

    # The headers accumulate in $compressor
    my %headers = $compressor->headers;
    
    # This goes into your Javascript
    print $headers{l};
    print $headers{p};

DESCRIPTION

This module implements the ideas from https://code.facebook.com/posts/991252547593574 to create the data needed for inline previews of images that can be served within the HTML page while keeping a low overhead of around 250 bytes per image preview. This is achieved by splitting up the preview image into a JPEG header which is common to all images and the JPEG image data. With a Javascript-enabled browser, these previews will be shown until the request for the real image has finished loading the data. This reduces the latency and bandwidth needed until the user sees an image.

It turns the following image

into 250 bytes of image data representing this image:

The Javascript on the client side then scales and blurs that preview image to create a very blurry placeholder until the real image data arrives from the server.

See below for the Javascript needed to reassemble the image data from the split header and scan data.

METHODS

Image::JpegMinimal->new( %OPTIONS )

  my $compressor = Image::JpegMinimal->new(
      xmax => 42,
      ymax => 42,
      jpegquality => 20,
  );

Creates a new compressor object. The xmax and ymax values give the maximum dimensions for the size of the preview image. It is suggested that the preview image is heavily blurred when presenting the preview image to the user to hide the JPEG artifacts.

$compressor->data_preview

  my $data_preview = $compressor->data_preview( $file );

Reads the JPEG data from a file and returns a base64 encoded string of the reduced image data. You stuff this into the data-preview attribute of the img tag in your HTML.

$compressor->headers

  my %headers = $compressor->headers;

After processing all files, this method returns the headers that are common to the images. You need to pass this to your Javascript.

HTML

Each image that has a pre-preview placeholder will need to store the placeholder data in the data-preview attribute. That is all the modification you need. You should also set the width and height attributes of the image so that no ugly image-popping occurs when the real data arrives. The $payload64 is the data that is returned from the ->data_preview call.

    <img width="${final_width}px" height="${final_height}px"
       data-preview="$payload64"
       src="$file"
       />

JAVASCRIPT

You will need to include some Javascript like the following in your page, preferrably near the end so the code runs right after the HTML has loaded completely but image loading has not yet fired.

The hash %headers should be set to the base64 encoded fixed headers as returned by the ->headers( $file ) call. The image HTML should have been constructed as outlined above.

    "use strict";

    var header = {
        l : atob("$headers{l}"),
        h : atob("$headers{p}"),
    };
    function reconstruct(data) {
        // Reconstruct a JPEG header from our special data structure
        var raw = atob(data);
        // Keep as "char" so we don't have to bother with Unicode vs. ASCII
        var width  = raw.charAt(0);
        var height = raw.charAt(1);
        var payload = raw.substring(2,raw.length);
        var head;
        if( width < height ) {
            head = header["p"]
        } else {
            head = header["l"]
        };
        var dimension_patch = width+height;
        var patched_header = head.substring(0,head.length-13)
                           + width
                           + head.substring(head.length-12,head.length-11)
                           + height
                           + head.substring(head.length-10,head.length);
        var reconstructed = patched_header+payload;
        var encoded = "data:image/jpeg;base64,"+btoa(reconstructed);
        return encoded;
    }

    var image_it = document.evaluate("//img[\@data-preview]",document, null, XPathResult.ANY_TYPE, null);
    var images = [];
    var el = image_it.iterateNext();
    while( el ) {
        images.push(el);
        el = image_it.iterateNext();
    };

    for( var i = 0; i < images.length; i++ ) {
        var el = images[ i ];
        if( !el.complete || el.naturalWidth == 0 || el.naturalHeight == 0) {
        
            var fullsrc = el.src;
            var loadsrc = reconstruct( el.getAttribute("data-preview"));
            var container = document.createElement('div');
            container.style.overflow = "hidden";
            container.style.display = "inline";
            container.style.position = "relative";

            var parent = el.parentNode;
            parent.insertBefore(container, el);
            container.appendChild(el);

            // Set up the placeholder data
            el.src = loadsrc;
            el.style.filter = "blur(8px)";
            var img = document.createElement('img');
            img.width = el.width;
            img.height = el.height;
            // Shouldn't we also copy the style and maybe even some events?!
            // img = el.cloneNode(true); // except this doesn't copy the eventListeners etc. Duh.
            (function(img,container,src) {
                img.onload = function() {
                    // Put the loaded child in the place of the preloaded data
                    parent.replaceChild(img,container);
                };
                var timeout = 1000+Math.random()*3000;
                // Kick off the loading
                // The timeout is just for demonstration purposes
                // window.setTimeout(function() {
                    img.src = src;
                //}, timeout);
            }(img,container,fullsrc));
        } else {
            // Image has already been loaded (from cache), nothing to do here
        };
    };

REPOSITORY

The public repository of this module is http://github.com/Corion/image-jpegminimal.

SUPPORT

The public support forum of this module is https://perlmonks.org/.

BUG TRACKER

Please report bugs in this module via the RT CPAN bug queue at https://rt.cpan.org/Public/Dist/Display.html?Name=Image-JpegMinimal or via mail to jpeg-minimal-Bugs@rt.cpan.org.

AUTHOR

Max Maischein corion@cpan.org

COPYRIGHT (c)

Copyright 2015 by Max Maischein corion@cpan.org.

LICENSE

This module is released under the same terms as Perl itself.