A library for generating Line Integral Convolutions

Line Integral Convolutions (LICs) are an amazing way to visualise 2D vector fields, and are widely used in many different fields (e.g., weather modelling, plasma physics, etc.), however I couldn't find a simple, up-to-date implementation, so I wrote my own. I hope it can now also help you on your own vector field fueled journey!

Here is the LIC code applied to a couple of example vector fields:

• Left: modified version of the Lotka-Volterra equations
• Right: a swirling pattern

Getting setup

You can now install the LIC package directly from PyPI or clone the Github repository if you'd like to play around with the source code.

Option 1: Install from PyPI (for general use)

If you only need to use the package, you can install it via pip:

pip install line-integral-convolutions

After installing, import the library as follows:

from vegtamr import lic

Inside this module, you will want to use the lic.compute_lic_with_postprocessing function. See below for details on how to get the most out of it.

Option 2: Clone the GitHub repository (for development)

1. Clone the repo:

git clone git@github.com:AstroKriel/LineIntegralConvolutions.git
cd LineIntegralConvolutions

2. Create a development environment with uv:

uv sync

This will install dependencies listed in pyproject.toml into a virtual environment managed by uv.

With uv you get clean package management and reproducibility, where the only trade-off is a few extra keystrokes when running scripts:

uv run demos/demo-lic.py

A small price to pay for sanity! Alternatively, you can activate the environment with source .venv/bin/activate and run python3 demos/demo-lic.py.

3. Use your local checkout from another project (optional):

uv sync (step 2) already gives you an editable install inside this repo's own .venv, so edits are picked up immediately when you work from here. If you want to use this edited clone in a different project, you will need to install it as an editable dependency from that project:

uv add --editable /path/to/vegtamr

Quick start

compute_lic_with_postprocessing is the main entry point for generating LICs. It manages all the internal calls and offers optional postprocessing: filtering and intensity equalisation. In practice, this is the only function you’ll need to call!

Here’s a quick example:

import matplotlib.pyplot as mpl_plot
from vegtamr import lic
from vegtamr.utils import vfields, plots

## generate a sample vector field
num_cells = 500
vfield_config = vfields.vfield_swirls(num_cells)
vfield = vfield_config.vfield
streamlength = vfield_config.streamlength

## apply the lic
sfield = lic.compute_lic_with_postprocessing(
    vfield=vfield,
    streamlength=streamlength,  # brush stroke length
    num_lic_passes=3,  # number of brush strokes
    use_filter=True,
    filter_sigma=5e-2 * num_cells,  # tube thickness
    use_equalize=True,
    backend="rust",
)

## and now plot!
fig, ax = mpl_plot.subplots()
plots.plot_lic(
    ax=ax,
    sfield=sfield,
    vfield=vfield,
    cmap_name="pink",
)
mpl_plot.show()

There are a number of parameters for you to experiment with; the effect of streamlength and postprocessing is demonstrated by demos/demo-streamlength.py, which produces the following image:

In practice you will want to choose a streamlength close to the correlation length (in cells) of the structures you are trying to highlight. Depending on the effect you're aiming for, you can also play around with turning on the highpass filter (use_filter), changing its size (filter_sigma; controls the thickness of tubes), and turning on intensity equalization (use_equalize).

You can also control the width of the brush strokes by smoothing the initial field that seeds the LIC, via seed_smoothing_sigma; this is demonstrated by demos/demo-seed-smoothing.py, which produces the following image:

By default seed_smoothing_sigma scales with the size of the domain, but you are free to tweak the value as you please; note, pushing it too high starts to introduce artefacts near saddle points.

Note: If you want a darker look without touching the underlying data, plot_lic also accepts cmap_range, e.g. cmap_range=(0.0, 0.75); this restricts which portion of the colormap is used, so the full value range maps smoothly to the restricted color range without clipping.

File structure

LineIntegralConvolutions/  # project root
├── src/
│   └── vegtamr/  # package root (named after Odin's alias, "Wanderer")
│       ├── __init__.py
│       ├── py.typed  # marker for type checkers (PEP 561)
│       ├── lic/
│       │   ├── __init__.py
│       │   ├── _api.py  # public-facing API
│       │   ├── _core.py  # core algorithms
│       │   ├── _parallel_by_row.py  # parallel implementation
│       │   ├── _postprocess.py  # filtering + equalisation
│       │   └── _serial.py  # serial implementation
│       └── utils/
│           ├── __init__.py
│           ├── plots.py  # plotting helpers
│           └── vfields.py  # example vector fields
├── demos/  # example scripts
│   ├── demo-lic.py  # simple demo
│   ├── demo-streamlength.py  # demo of how streamlength and postprocessing affect LIC output
│   └── demo-seed-smoothing.py  # demo of how seed_smoothing_sigma affects LIC output
├── gallery/  # reference images
├── pyproject.toml  # project metadata and dependencies
├── uv.lock  # lock file (used by uv to pin dependencies)
├── LICENSE  # terms of use and distribution
└── README.md  # this file

Acknowledgements

Both the fast (pre-compiled Rust) LIC backend, rLIC (which this repo uses by default), and the histogram-equalization backend, ahe, were implemented by Dr. Clément Robert (@neutrinoceros). Special thanks also go to Dr. James Beattie (@AstroJames) for highlighting how iteration, high-pass filtering, and histogram normalisation improve the final result. Finally, Dr. Philip Mocz (@pmocz) provided lots of helpful suggestions in restructuring and improving the codebase.

License

This project is licensed under the MIT License; see the LICENSE file for details.