README

README
Author: Cary Yang <caryy@andrew.cmu.edu>

---------------------------------------------------------------------------
Overview
---------------------------------------------------------------------------

This project is a C++ implementation of Depixelizing Pixel Art, by Kopf and
Lischinski, SIGGRAPH 2011, written for my final project in CMU's 15-463,
Computational Photography.

This code has only been tested on the files in the images/ directory, it is
likely to contain bugs. Also, the optimization phase does not appear to
work correctly (output does not match paper's results).

What follows is instructions on building the code, running the program, and
a description of the source files.

This README and the CMake build system for this project were largely adapted
from projects in CMU's 15-462, Computer Graphics.

---------------------------------------------------------------------------
Prerequisites
---------------------------------------------------------------------------

There are some libraries required for this to compile, namely OpenCV (for
image reading/writing and colorspace conversion) and Boost (for the Voronoi
diagram and filesystem utilities).

---------------------------------------------------------------------------
Building the Code
---------------------------------------------------------------------------

This project uses the CMake build system (www.cmake.org). CMake is a kind of
"meta build-system," in that it creates a build system for you. It supports
many different build systems, ranging from Unix Makefiles to Visual Studio
projects to XCode projects.

1) If you don't have CMake installed, you should install it. If you're running
    Linux, it should be available through your disto's package manager
    (apt-get, pacman, ports, etc). Windows and OSX installers can be downloaded
    from http://www.cmake.org/cmake/resources/software.html
2) Open up a command prompt in the "build" directory and run "cmake ../src".
    CMake will generate the build system in the build directory. By default,
    CMake will generate Makefiles on Linux and OSX and a Visual Studio project
    on Windows. If you'd like to change that, you can pass a different
    "generator" to cmake with the -G flag. A full list of generators can be
    found at the bottom of the output generated by running "cmake". For
    example, "cmake -G 'Xcode' ../src" will generate an Xcode project on OSX.
3) You can now use the build system in the "build" directory. The default
    target will compile everything for you, and the "install" target will copy
    the executable to the main "final_project" directory.

NOTE: This project has only been tested on OS X Yosemite, compilation on other
targets is not gauranteed.

WARNING: This project will only compile with GNU-based compilers and will most
likely not run on Windows as the proper runtime libraries are not included.

---------------------------------------------------------------------------
Running the Program
---------------------------------------------------------------------------

./depixelize [options] input_filename
Program Options:
  -o  --output <FILENAME>
      Puts the resulting image into <FILENAME> (default: [input_filename]_out)
  -s  --scale  <INT>
      Scale the output image by this factor (default: 16)
  -h  --help
      This message
  input_filename
      The input image to depixelize

---------------------------------------------------------------------------
Source Files and Directory Structure
---------------------------------------------------------------------------

A description of the top-level directories and all source/header file pairs
follows.

README                   -- this file

images/                  -- a set of input images from the original paper
                             (C) Nintendo Co., Ltd

src/build/*              == Build system stuff.
    CMakeLists.txt       -- Compiler flags can be adjusted by editing the
                              list in here.

src/depixelize/          == Project-specific files.
    main                 -- Main function, and application backend.
    pixel_grid           -- An implementation of an 8-connected pixel grid
                              that can make itself planar and resolve
                              ambiguities.
    spline_optimizer     -- Extracts and optimizes splines from the Voronoi
                              diagram.
    color_util           -- Various color utility functions.
    math_util            -- Various math utility functions.
    voronoi_visual_utils -- Voronoi utilities, borrowed from the
                              voronoi_visualizer example in Boost.

src/geometry/            == Geometry related classes and functions
    bspline              -- Contains a B-spline implementation that can
                              find its own curvature and be integrated.
    edge                 -- Simple undirected-edge made from 2 points.
    point                -- Simple point implementation, with some math
                              utility operators implemented.
    shape                -- A shape, defined by a B-spline edge and a list
                              of internal color points.
    types                -- Various common types.

src/render/              == Rendering related classes
    renderer             -- Base interface for all renderers. Defines
                              rendering lists of shapes to arbitrary
                              formats.
    svg_renderer         -- SVG implementation of the renderer.
    simple_svg_1.0.0     -- An SVG rendering library from the Internets.