image-visibility-graph
A Python implementation of Image Visibility Graphs and Visibility Patches, the image-analysis method introduced by Iacovacci & Lacasa, Visibility graphs for image processing, IEEE TPAMI 42(4), 974–987 (2020) (doi:10.1109/TPAMI.2019.2891742, arXiv:1804.07125).
The package is imported as ivg. Its only hard dependency is NumPy, and every computation is vectorized.
Features
-
Both visibility criteria everywhere, selected with
criterion=:criterionGraph Local features Order-3 motif (Table I of the paper) "natural"IVG VPp x₂ > 2x₁ − x₀ "horizontal"IHVG HVPp x₁ < min(x₀, x₂) -
Visibility Patch profile Z (local features) of any order p ≥ 3, including the 4(p−2) off-diagonal motifs that the paper adds for p ≥ 4.
-
Full image graph (global features): pixels linked along rows, columns, diagonals and anti-diagonals. Gives the degree map ("k-filtered image"), the degree distribution P(k), and export to a SciPy sparse matrix or NetworkX graph.
-
Interpretable labels:
decode_labeltells you which rows, columns and diagonals carry which motif. -
Exact comparisons: images are handled as
float64, so integer and real-valued images (e.g. normalized to [0, 1]) are processed without truncation.
Installation
pip install git+https://github.com/sierraporta/image-visibility-graph
or, for development:
git clone https://github.com/sierraporta/image-visibility-graph
cd image-visibility-graph
python -m venv .venv && source .venv/bin/activate
pip install -e ".[extras,test,examples]"
The optional extras are NetworkX, SciPy, pandas, OpenCV/Pillow (image loading) and Matplotlib/Jupyter for the examples.
Quick start
import ivg
img = ivg.load_gray("my_image.png") # 2D grayscale array
# Local features: Horizontal Visibility Patches of order 3 (256 possible patches)
prof = ivg.patch_profile(img, order=3, criterion="horizontal")
Z = prof.to_dense(normalize=True) # feature vector of length 256
prof.most_common(5) # [(label, count), ...]
ivg.decode_label(135, order=3) # {'r1': 1, 'r2': 0, ..., 'd1': 1, 'd2': 0}
# Global features: the full Image Visibility Graph
G = ivg.image_visibility_graph(img, criterion="natural")
K = G.degree_map() # k-filtered image, same shape as img
Pk = G.degree_distribution(kmax=100) # fixed-length P(k)
A = G.adjacency() # scipy.sparse CSR matrix
For a feature matrix over several images (rows aligned to a common label set):
profiles = [ivg.patch_profile(im, order=3, criterion="horizontal") for im in images]
X, labels = ivg.profile_matrix(profiles) # X.shape == (n_images, n_labels)
A complete example is in examples/example_ivg.ipynb. It runs on synthetic
textures with tunable spatial correlation and on a real solar image from SDO/HMI, comparing an active
region with the quiet Sun.
Method
Image Visibility Graph
Every pixel is a node. Two pixels are linked if they lie on the same row, column, diagonal or anti-diagonal and "see" each other in the 1D visibility graph of that line:
- natural: xk < xa + (xb − xa)(k − a)/(b − a) for all a < k < b
- horizontal: xk < min(xa, xb) for all a < k < b
Visibility Patches and label convention
A Visibility Patch of order p is the subgraph of the IVG/IHVG induced by a p×p window, slid over the image with stride 1. The patch is fully determined by the sequential visibility motif of each line of the window, in this order:
V = [r1..rp, c1..cp, d1, d2, d1+1, d1-1, d2+1, d2-1, d1+2, d1-2, ...]
Here d1 is the main diagonal and d2 the anti-diagonal, which runs from top-right to
bottom-left as in the paper. d1±o and d2±o are the off-diagonals shifted by o.
Each line's motif is encoded by which of its non-adjacent pairs (a, b), b − a ≥ 2, are
visible. The patch label is 1 + concatenated bits, with the first line as the most
significant bits.
For p = 3 this is exactly the paper's encoding: L = 1 + Σ Vi 28−i, with 256 possible labels. For example, V = [1,0,0,0,0,1,1,0] gives L = 135 (Fig. 4 of the paper).
A note on higher orders
For p ≥ 4, each line can take more than two motifs, and the off-diagonals add more
lines. The label space therefore grows very fast (234 labels for p = 4,
288 for p = 5), and real images use only a tiny fraction of it.
PatchProfile stores profiles sparsely, profile_matrix aligns them across images,
and label_map() / decode_label() work for any order. As a feature vector, p = 3 is
usually the practical choice, which is also the order used in the paper.
API overview
| Function / class | Purpose |
|---|---|
patch_profile(img, order, criterion, stride) → PatchProfile |
Visibility Patch profile (sparse; .to_dense(), .frequencies(), .to_series(), .label_map(), .most_common()) |
profile_matrix(profiles, normalize, labels) |
Aligned feature matrix for several images |
patch_label_map(img, order, criterion, stride) |
Label of the patch anchored at every pixel (p ≤ 4) |
patch_codes(img, order, criterion) |
Raw per-line motif codes of every patch |
decode_label(label, order) / decode_label_edges(...) |
Interpret a label |
patch_layout(order), label_bits(order), n_labels(order) |
Patch geometry and label-space size |
paper_to_matlab_label, matlab_to_paper_label |
Convert order-3 labels to/from the numbering of the reference MATLAB code |
image_visibility_graph(img, criterion, directions, lattice) → ImageVisibilityGraph |
Full IVG/IHVG (.edges, .degrees(), .degree_map(), .degree_distribution(), .adjacency(), .to_networkx()) |
degree_map(img, criterion) |
Shortcut for the k-filtered image |
visibility_graph_edges(series, criterion) |
VG/HVG of a 1D series |
motif_codes(lines, criterion), code_to_edges, admissible_motifs |
Sequential visibility motifs |
load_gray(path) |
Load an image as grayscale (raises if the file is missing) |
Validation
The test suite (python tests/test_ivg.py, or pytest) checks the implementation
against independent references:
- Algorithm 1 of the paper: a literal transcription for p = 3 gives identical profiles, for both criteria.
- Fig. 4 of the paper: the example decodes to label 135.
- Full graph: matches a brute-force construction over all pixel pairs in exact rational arithmetic, including images with ties.
- 1D graph: the natural VG matches
networkx.visibility_graph. - White noise: HVG link probabilities follow the exact law 2/[d(d+1)] (Luque et al., 2009).
- Patches of order 3, 4 and 5: each patch equals the subgraph that the full graph induces on its window. This cross-checks the two modules against each other.
- Admissible motifs and patches:
- The number of admissible HVG motifs follows the Catalan numbers (1, 2, 5, 14, 42).
- Continuous noise produces exactly the 188 distinct HVP3 patches reported in the paper.
- Invariance: the horizontal criterion is invariant under strictly increasing intensity transforms.
Cross-validation against the reference implementation
ivg was also compared with the MATLAB code by the paper's first author
(Jaia89/Image_Visibility), run in GNU Octave.
The test images included many repeated values, real-valued images, white noise, correlated
surfaces and the 512×512 image that ships with that repository. The Visibility Patch
profiles (both criteria) and the full IVG/IHVG edge sets are identical.
The reference code numbers the 256 order-3 patches differently from Algorithm 1 of the paper.
ivg follows the paper, and to_dense(numbering="matlab") gives the reference numbering.
Scripts and details: validation/matlab_reference.
Performance
Timings on a laptop CPU (NumPy only):
| Image | Patch profile p = 3 | Patch profile p = 5 | Full graph |
|---|---|---|---|
| 512 × 512 | < 0.1 s | ~1.5 s | 1.6 s (IHVG) / 2.7 s (IVG) |
| 1024 × 1024 | ~0.2 s | ~4.5 s | 12 s (IHVG) / 15 s (IVG) |
Patch profiles scale linearly with the number of pixels. The full graph costs O(N³) for an N × N image in the worst case.
Related software
- Jaia89/Image_Visibility: MATLAB
functions (GPL-3.0) by the paper's first author to extract IVGs and Visibility Patch
profiles.
ivgreproduces their output exactly (see Validation). - ts2vg: fast natural and horizontal visibility graphs for time series (1D).
- Lucas Lacasa's visibility graph page: original codes, e.g. MATLAB motif scripts.
Citing
If you use this package, please cite the original method:
@article{iacovacci2020visibility,
title = {Visibility Graphs for Image Processing},
author = {Iacovacci, Jacopo and Lacasa, Lucas},
journal = {IEEE Transactions on Pattern Analysis and Machine Intelligence},
volume = {42},
number = {4},
pages = {974--987},
year = {2020},
doi = {10.1109/TPAMI.2019.2891742}
}
Related foundational work:
- L. Lacasa, B. Luque, F. Ballesteros, J. Luque, J. C. Nuño, From time series to complex networks: The visibility graph, PNAS 105, 4972 (2008). doi:10.1073/pnas.0709247105
- B. Luque, L. Lacasa, F. Ballesteros, J. Luque, Horizontal visibility graphs: Exact results for random time series, Phys. Rev. E 80, 046103 (2009). doi:10.1103/PhysRevE.80.046103
- J. Iacovacci, L. Lacasa, Sequential visibility-graph motifs, Phys. Rev. E 93, 042309 (2016). doi:10.1103/PhysRevE.93.042309
- J. Iacovacci, L. Lacasa, Sequential motif profile of natural visibility graphs, Phys. Rev. E 94, 052309 (2016). doi:10.1103/PhysRevE.94.052309
License
Code: MIT © 2026 David Sierra Porta.
Example data: the solar image in examples/data/ is courtesy of NASA/SDO and the AIA, EVE,
and HMI science teams. SDO images are not copyrighted unless explicitly noted
(SDO data rules). See
examples/data/README.md.
Metadata
Release files for image-visibility-graph 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| image_visibility_graph-0.1.0.tar.gz | 22.3 kB | With provenance | Details for image_visibility_graph-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| image_visibility_graph-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for image_visibility_graph-0.1.0-py3-none-any.whl |
Total release size: 42.7 kB
Release files / image_visibility_graph-0.1.0.tar.gz
| Download URL | image_visibility_graph-0.1.0.tar.gz |
|---|---|
| Size | 22.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
25263abfb3e325176692fb5d619ef37c51290cc5a30fad3ea907a7a2b5faf42d
|
|
BLAKE2b-256 checksum How to use checksums |
06908b411858ccd0a0b705eb3ca5877e4cf6e2064a7b8029e976688ab57b72e1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / image_visibility_graph-0.1.0-py3-none-any.whl
| Download URL | image_visibility_graph-0.1.0-py3-none-any.whl |
|---|---|
| Size | 20.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
89b56fbbf5dda3629347e2fc71a64bdcd4f2a21a55d210ce98962d8a62dc53c0
|
|
BLAKE2b-256 checksum How to use checksums |
f9182ee35b3a2f4899692f7f85d91530c835df0abf4896a230fb8c7939d69d1a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logSecurity for image-visibility-graph 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for image_visibility_graph-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.