Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

ivpy: Iconographic Visualization in Python

Read the journal article here.

Tutorial Dataset

A detailed guide to using ivpy is included here, in the tutorial notebooks. To avoid data access issues, I've written the tutorials using the publicly available Oxford Flower 17 dataset. It contains 80 images each of 17 different flower types. I've included a data table, oxfordflower.csv, in the ivpy repo, but you'll need to download the images themselves here. The filename column in oxfordflower.csv corresponds to the filenames in the linked archive.

Basic Install

I recommend cloning this repo into your home directory, creating and activating a Python virtual environment, and pip installing the dependencies:

$ git clone
$ python3 -m venv ivpy_env
$ source ivpy_env/bin/activate
$ pip install numpy notebook pandas Pillow

Custom CSS theme

If you want to use my custom jupyter theme, optimized for viewing image visualizations:

$ mkdir ~/.jupyter/custom
$ cp ~/ivpy/style/custom.css ~/.jupyter/custom


Some of the plots include text labels, and for that, I include a directory of fonts, because the defaults in PIL are pretty bad. You'll need to copy the font directory to your home directory:

$ cp -r ~/ivpy/fonts ~

Basic Usage

import pandas as pd
import sys,os
sys.path.append(os.path.expanduser("~") + "/ivpy/src")
from ivpy import *

df = pd.DataFrame(...)
imagecol = '...'

attach(df, imagecol)

# scrollable panel of images / glyphs

# by default, a square montage of images

# image histogram

# image scatterplot
scatter(xcol='foo', ycol='bar')

Additional functionality

There is a great deal more in ivpy, including image feature extraction (requires additional dependencies, like scikit-image and others); glyph drawing; line plots; clustering algorithms and dimension reduction (with scikit-learn under the hood); image resizing and slicing; image signal processing; and even nearest neighbor search (using annoy).