Skip to content

Latest commit

 

History

History
108 lines (95 loc) · 4.68 KB

README.md

File metadata and controls

108 lines (95 loc) · 4.68 KB

photog

Computational photography library built on Halide.

photog takes advantage of Halide's unique strengths...

  • Separation of algorithms from their mapping onto resources (scheduling).
  • Auto-scheduling based on hardware features, image size, and image memory layout.
  • Auto-scheduling support for many CPU platforms.
  • The ability to produce extremely performant algorithms while just focusing on the algorithms!

...to produce a computational photography library that provides performant functions tuned to the hardware and images you wish to run them on.

Configuration

photog will use Halide's auto-scheduling to compile versions of its functions that are tuned for the platform you are compiling on. Auto-scheduling is also dependent on image memory layout and expected dimensions. photog provides the following hooks to specify that information:

CMake Option Environment Variable Default Description
PHOTOG_IMAGE_LAYOUT PHOTOG_IMAGE_LAYOUT planar Valid options are planar and interleaved. Planar images are contiguous in channels while interleaved images are contiguous in pixels. Best performance is achieved with planar images.
PHOTOG_IMAGE_WIDTH_ESTIMATE PHOTOG_IMAGE_WIDTH_ESTIMATE 500 Expected width in pixels of images to be processed.
PHOTOG_IMAGE_HEIGHT_ESTIMATE PHOTOG_IMAGE_HEIGHT_ESTIMATE 500 Expected height in pixels of images to be processed.

Image dimension estimates provide a guideline for scheduling and in most cases do not exclude smaller or larger images.

Building

Dependencies

photog depends on the following libraries:

  • Halide 17 (fetched from official repo)
  • doctest 2.4 (fetched from official repo)
  • libjpeg (only if building tests and not fetched automatically)
  • libpng (only if building tests and not fetched automatically)

You will also need a C++17 compiler.

Build/Install Commands

$ git clone https://github.com/kyleingraham/photog.git
$ cmake -DCMAKE_BUILD_TYPE=Release \
        -DPHOTOG_IMAGE_LAYOUT=planar \
        -DPHOTOG_IMAGE_WIDTH_ESTIMATE=500 \
        -DPHOTOG_IMAGE_HEIGHT_ESTIMATE=500 \
        -G "<Your choice of generator>" \
        ./photog/
$ cmake --build ./photog/cmake-build-release --target install

On Windows, CMake's Ninja generator will not work. Use a Visual Studio generator instead.

Usage via CMake

To use photog in your CMake project add the following command to your CMakeLists.txt:

find_package(photog)

The following variables and targets will be made available:

Set Variables

Variable Description
photog_VERSION Full version string
photog_VERSION_MAJOR Major version string
photog_VERSION_MINOR Minor version string
photog_VERSION_PATCH Patch version string
photog_VERSION_TWEAK Tweak version string
photog_TARGET Halide target triple (arch-bits-os) used to compile photog
photog_IMAGE_LAYOUT Image layout (planar or interleaved) used to complile photog
photog_IMAGE_WIDTH_ESTIMATE Image width estimate in pixels used to compile photog
photog_IMAGE_HEIGHT_ESTIMATE Image height estimate in pixels used to compile photog

Imported Targets

Target Description
photog::color Makes available the photog/color.h header containing functions for manipulating image colors/color spaces.

Available Functions

Defined in header photog/color.h (photog::color target):

/** Chromatically adapt RGB input from the estimated source illuminant of the
 * input image to the given destination illuminant.
 *
 * The source illuminant is estimated using the gray-world method.
 */
void photog_chromadapt(float *input, int width, int height,
                       PhotogWorkingSpace working_space,
                       PhotogChromadaptMethod chromadapt_method,
                       PhotogIlluminant dest_illuminant, float *output);

/** Chromatically adapt RGB input from the given source illuminant to the given
 * destination illuminant.
 *
 * Here both the source and destination tristimulus values must be supplied by
 * the user hence the "_diy" prefix.
 */
void photog_chromadapt_diy(float *input, int width, int height,
                           float *source_tristimulus,
                           PhotogWorkingSpace working_space,
                           PhotogChromadaptMethod chromadapt_method,
                           float *dest_tristimulus, float *output);

Detailed function descriptions are available in their respective headers.

Missing Functionality

  • Easy cross-compilation
  • GPU support