LiquidRescale library 0.4.0
===========================

Table of contents
-----------------
  * Introduction
    + Library features
  * Installation
    + Requirements
    + Normal setup
  * Using the library
  * References
  * Copyright


+ Introduction
--------------

The LiquidRescale (lqr) library provides a C/C++ API for
performing non-uniform resizing of images by the seam-carving
technique.

++ Library features

The library takes images in plain array format as input
and converts them to a multi-size representation.
Following is a list of features:

  * Easy to use and fully documented API
  * Currently supports 8 bit to 64 bit per channel images
  * Support for different color models: grayscale, RGB, CMY
    and their variants, and even custom ones
  * Areas in the image can be marked for preservation or
    discard, or for additional seam rigidity
  * Once the image has been fully processed, the scaling can
    be done in real-time. In fact, the information can be saved
    and read out later without any further processing
  * The resizing is done with a single function which
    automatically performs all the necessary operations; it
    can also work in successive steps without wasting
    computational time
  * Possibility to tune the carving operation by letting the
    seams be less connected, or more rigid, or both (the
    rigidity can be also be modulated through a mask, to get
    a differnet behaviour in different areas of the image)
  * Can export and import the visibility map (the seams)
  * Other images can be attached and undergo the same carving
    process as the parent image
  * The automatic feature detection algorithm can be tuned
    by selecting among different energy gradient functions,
    and easily defining custom ones
  * Reports progress through a customisable interface
  * A signalling system permits to cleanly handle errors
  * Portable to all major OS's



+ Installation
--------------

++ Dependencies

The lqr library depends on the glib-2.0 libraries

++ Normal setup

The build package uses autotools and libtool, so the installation
commands on Unix systems are simply

./configure && make && sudo make install

The last step requires administrative privileges.
(Note: the default installation path is /usr since version 0.4)

If you want to also install the man pages for the library functions,
add the option `--enable-install-man' in the call to ./configure.

If you want to disable legacy macro names which do not begin with
LQR_ then add the option `--diable-legacy-macros'

See the INSTALL file for a full description.



+ Using the library for development
-------------------------------------

In order to use the library functions and structures from
a C or C++ program, you have to add this include line in
your program:

#include <lqr.h>

At compile time, you can take advantage of pkg-config to set
the proper flags.

In the `examples' directory you can find a basic example program,
`liquidrescale-basic', and a full-featured demo program,
`liquidrescale', together with a simple Makefile. Both
programs are fully commented.

The "basic" version demonstrates how to use the strictly-needed
library functions, while the full version uses almost all of the
API methods provided. The Makefile shows how to set the compilation
flags.

See the README file in that directory for more information.

The complete manual and reference for the library, together with
some additional notes, can be found in the `docs' directory in
docbook format. The reference is also provided in man page format.
The makefile in that directory (hopefully) generates the manual in
html format, using xsltproc; then you'll find the index named after
`liblqr_manual_index.html'.
See the README file in that directory for further information.



+ References
------------

The library implements the algorithm described in the paper
"Seam Carving for Content-Aware Image Resizing"
by Shai Avidan and Ariel Shamir, which can be found at
http://www.faculty.idc.ac.il/arik/imret.pdf



+ Copyright
-----------

Copyright (C) 2007-2009 Carlo Baldassi <carlobaldassi@gmail.com>

Compiling the library in Windows
================================

DISCLAIMER: these notes are not very reliable, as they're
based on some very simple tests, without much knowledge of
the Windows operating system.

1) Using MinGW/MSYS

Everything goes as in standard *nix systems (you should
probably change the default installation location with the
--prefix option in `configure').
With the default options, the `configure' sctipt produces a
DLL.  If you want to build a static library, you should pass the
options --disable-shared and --disable-declspec to
`configure', and make sure you define the preprocessor
LQR_DISABLE_DECLSPEC whenever you want to compile/link
against the static library.

2) Using MS Visual C++

The library compiles with `Microsoft Visual C++ 2008 Express
edition' and `Microsoft Visual C++ 2010 Express Edition'.
Follow these steps:

  a) Create a new project (suggested name: `liblqr-1-0')

   *) In the 2008 edition, create an empty DLL project with
      the default setup (choose Console Application then
      Advanced Settings -> DLL + Empty Project). The
      suggested name is liblr-1-0

   *) In the 2010 edition, choose Empty project

  b) Copy the `lqr' directory in the project directory you
  have created

  c) Add all the source files within the `lqr' directory to
  the project (right-click -> Add -> Existing item...)

  d) Go to Project -> Properties in the menu. This opens a
  dialog. At the top, set "Configuration:" to "All
  Configurations". Then, go to "Configuration Properties"
  and set the options as follows:

   *) [2010 edition only] General -> Configuration Type:
      Dynamic Library

   *) C/C++ -> General -> Additional Include Directories:
      add the directory `lqr' and its parent, and also the
      directory where all the necessary glib-2.0 headers are
      found (usually, there are 2 of those, one ends with
      `include\glib-2.0', another with
      `lib\glib-2.0\include')

   *) C/C++ -> Preprocessor -> Preprocessor Definitions: add
      LQR_EXPORTS to the list

   *) C/C++ -> Advanced -> Compile As: Compile as C Code (it
      also works otherwise, but this option seems to make
      sense given that the library is ANSI C)

   *) Linker -> General -> Version: set version number

   *) Linker -> General -> Additional Library Directories:
      add the directory where glib-2.0.lib is found

   *) Linker -> Input -> Additional Dependencies: add
      glib-2.0.lib

When you build the project, it should produce the library
liblqr-1-0.lib and liblqr-1-0.dll files (assuming your
project is called `liblqr-1-0').