unflattener
Unflattener is a free and open source Python module and a command line tool (unflatten) that helps you make normal maps for 2D sprites and other graphics. You can use the normal maps it generates to implement dynamic lighting in video games.
Example
How it works
Unflattener takes as input images of your object lit by a light source pointing directly at that object from four directions: top, bottom, left and right (we'll call those images "directionally lit" or "d-lit" for short — like "d-pad"). At least one such image is required; having at least two (one with light coming from the top or the bottom, one with light from the left or the right) is highly recommended.
Unflattener is written in Python and requires the libraries NumPy and Pillow to work. Python programs can access its functionality directly by importing the NormalMap class from the module unflattener.normalmapgen. Right now Unflattener cannot do dynamic lighting previews, so you will need a third-party tool like the gimp-normalmap plugin for GIMP for that.
This project was inspired by Sprite Lamp.
The core algorithm is explained in a rather lengthy comment in the method NormalMap.create_from_images in normalmapgen.py. You will find some tips on how the input artwork should look in the same comment.
The general idea is that in the d-lit images your object should look as if it were
- Uniformly matte white with no self-shadowing;
- Lit by a very distant light source much larger than itself that creates no highlights.
Installation
Unflattener has been tested to work under Linux (Ubuntu 12.04, Ubuntu 16.04, Fedora 26, Debian 7 and openSUSE Tumbleweed 2017*) and Windows (XP, 7, 8.1 and 10).
You will need Python 2.7 (v2.6 and earlier won't work) or Python 3.2 or later, NumPy and Pillow to run Unflattener. The following instructions are for Python 2.7.
Debian and Ubuntu
You can install the dependencies from the distribution's package repository with
sudo apt install git python-numpy python-imaging python-setuptools
To install gimp-normalmap, run
sudo apt install gimp-normalmap
To install Unflattener, clone this repository, cd into it and run setup.py:
git clone https://github.com/dbohdan/unflattener
cd unflattener
python setup.py install --user
Fedora
You can install the dependencies from the distribution's package repository with
sudo dnf install git numpy python-pillow python-setuptools
To install gimp-normalmap, run
sudo dnf install gimp-normalmap
To install Unflattener, clone this repository, cd into it and run setup.py:
git clone https://github.com/dbohdan/unflattener
cd unflattener
sudo python setup.py install
Windows
On Windows you first need to install Python 2.7 using the official installer from http://python.org/download/. Unflattener has only been tested with the 32-bit versions of Python, NumPy and Pillow (on both 32-bit and 64-bit Windows), so it is recommended that you use those.
Once you have Python installed, download the latest binary packages for NumPy and Pillow from http://www.lfd.uci.edu/~gohlke/pythonlibs/. They will be named, e.g., numpy-1.13.1+mkl-cp27-cp27m-win32.whl and Pillow-4.2.1-cp27-cp27m-win32.whl. Open the Command Prompt in the directory where you downloaded the package files and run
c:\Python27\python.exe -m pip install "numpy-1.13.1+mkl-cp27-cp27m-win32.whl"
c:\Python27\python.exe -m pip install Pillow-4.2.1-cp27-cp27m-win32.whl
To install Unflattener, clone this repository with Git for Windows or download https://github.com/dbohdan/unflattener/archive/master.zip and unzip it, cd into the created directory and do
c:\Python27\python.exe setup.py install
You should then be able to run Unflattener from the Command Prompt with the command unflatten. If you don't have the Python 2.7 scripts directory added to your %PATH%, try
c:\Python27\Scripts\unflatten.exe
Usage
usage: unflatten.py [-h] [--top TOP] [--bottom BOTTOM] [--left LEFT]
[--right RIGHT] [--output OUTPUT] [--depth DEPTH]
Generate a normal map for 2D art
optional arguments:
-h, --help show this help message and exit
--top TOP, -t TOP top image file
--bottom BOTTOM, -b BOTTOM
bottom image file
--left LEFT, -l LEFT left image file
--right RIGHT, -r RIGHT
right image file
--output OUTPUT, -o OUTPUT
output file name
--depth DEPTH, -d DEPTH
normal map z_N range
One input file minimum, at least two (one for each axis) highly recommended.
Input files should be 8-bit grayscale PNGs.
Submit your work
If you use Unflattener to create artwork or video game graphics, file an issue to have your work featured here.
License information
Unflattener is distributed under the new (3-clause) BSD license. See the file LICENSE.
Robot sprite originally from the Bits & Bots art pack by MoikMellah. The sprite is licensed under the Creative Commons CC0 license.