A lightweight, extendible, easy to use Python package for deep dreaming and image generation with Caffe and CNNs.
Python Shell
Latest commit 894af13 Aug 5, 2015 @jrosebr1 Merge pull request #3 from superandoni/master
Forced 244x244 resizing of guide image
Failed to load latest commit information.
LICENSE Initial commit Jul 3, 2015
README.md Another update to the README Jul 11, 2015
demo_bulk.py Quick update to demo_bulk.py Jul 5, 2015



We can't stop here, this is bat country. — Raoul Duke

The bat-country package is an easy to use, highly extendible, lightweight Python module for inceptionism and deep dreaming with Convolutional Neural Networks and Caffe. My contributions here are honestly pretty minimal. All the real research has been done by the Google Research Team — I'm simply taking the IPython Notebook, turning it into a Python module, while keeping in mind the importance of extensibility, such as custom step functions.

If you're looking for a more advanced CNN visualization tool, check out Justin Johnson's cnn-vis library.


The bat-country packages requires Caffe, an open-source CNN implementation from Berkeley, to be already installed on your system. I detail the steps required to get Caffe up and running on your system in the official bat-country release post. An excellent alternative is to use the Docker image provided by Tomasz of Vision.ai. Using the Docker image will get you up and running quite painlessly.

After you have Caffe setup and working, bat-country is a breeze to install. Just use pip:

$ pip install bat-country

You can also install bat-country by pulling down the repository and setup.py:

$ git clone https://github.com/jrosebr1/bat-country.git
$ pip install -r requirements.txt
$ python setup.py install

A simple example

As I mentioned, one of the goals of bat-country is simplicity. Provided you have already installed Caffe and bat-country on your system, it only takes 3 lines of Python code to generate a deep dream/inceptionism image:

# we can't stop here...
bc = BatCountry("caffe/models/bvlc_googlenet")
image = bc.dream(np.float32(Image.open("/path/to/image.jpg")))

After executing this code, you can then take the image returned by the dream method and write it to file:

result = Image.fromarray(np.uint8(image))

And that's it!

For more information on bat-country, along with more code examples, head over to the the official announcement post on the PyImageSearch blog:


Guided dreaming

Google has also demonstrated that it's possible to guide your dreaming process by supplying a seed image. This method passes your input image through the network in a similar manner, but this time using your seed image to guide the output.

Using bat-country, it's just as easy to perform guided dreaming as deep dreaming. Here's some quick sample code:

bc = BatCountry(args.base_model)
features = bc.prepare_guide(Image.open(args.guide_image), end=args.layer)
image = bc.dream(np.float32(Image.open(args.image)), end=args.layer,
    iter_n=20, objective_fn=BatCountry.guided_objective,

What's nice about this approach is that I "guide" what the output image looks like. Here I use a seed image of Vincent van Gogh's Starry Night and apply to an image of clouds:

As you can see, the output cloud image after applying guided dreaming appears to mimic many of the brush strokes of Van Gogh's painting:

Here's another example, this time using a seed image of an antelope:

You can read more about guided dreaming, plus view more example images here:


Some visual examples

Below are a few example images generated using the bat-country package: