VisTopics

RPython

PyPI Python Versions License: MIT Downloads Docs How to Cite

VisTopics

vistopics (Topic Visualization for Visuals) is a Python package for video and image processing, offering features such as:

This package is designed for developers, researchers, and data scientists working on media processing, visualization, or clustering tasks.

Installation

Install vistopics from PyPI using:

pip install vistopics

If you plan to use FastDup for duplicate frame detection, install with:

pip install vistopics[fastdup]

Alternatively, install it directly from the source:

git clone https://github.com/aysedeniz09/VisTopics
cd VisTopics
pip install .

Note: The repository name on GitHub is VisTopics (capitalized), but the package name and Python import name are lowercase vistopics.

Features

Option A: Video-Based Pipeline

  1. Scrape and download videos from URLs
  2. Extract frames from the downloaded videos
  3. Reduce duplicate frames with FastDup
  4. Generate captions for the cleaned set of frames

Option B: Image URL-Based Pipeline

  1. Download images from a CSV containing article or image URLs
  2. Generate captions for the images

Requirements

The following Python libraries are required:

Note: To use FastDup-based functionality (limiting_frames), you must additionally install:

pip install vistopics[fastdup]

Install base dependencies with:

pip install -r requirements.txt

Usage

Option A: Video-Based Pipeline

1. Video Scraping

from vistopics import video_download

video_download(
    input_df_path="test_data.csv",
    output_df_path="cleaned_videos.csv",
    output_dir="downloaded_videos",
    link_column="Link",
    title_column="Page Name"
)

2. Frame Extraction

from vistopics import extract_frames

extract_frames(
    videofolder="downloaded_videos",
    images_folder="images",
    frame_rate=1
)

3. Duplicate Frame Reduction

from vistopics import limiting_frames

limiting_frames(
    path="images",
    output_file="reduced_frame_list.csv",
    ccthreshold=0.8
)

This step requires the optional fastdup dependency:

pip install vistopics[fastdup]

4. Caption Generation

from vistopics import get_caption

get_caption(
    mykey="your-open-ai-api-key",
    path_in="images",
    captions_file="captions_file.csv",
    model="gpt-4o-mini"
)

See Option B, Step 2 below for full get_caption documentation, including custom prompts and Anthropic/Claude support.

Option B: Image URL-Based Pipeline

1. Download Images from URLs

from vistopics import download_images_from_url

download_images_from_url(
    input_csv="output/urls_cvs.csv",
    output_csv="output/download_log.csv",
    image_dir="images",
    url_column="image_link",
    index_column="uuid",
    use_referer=True,
)

2. Caption Generation

from vistopics import get_caption

get_caption(
    mykey="your-open-ai-api-key",
    path_in="images",
    captions_file="captions_file.csv",
    model="gpt-4o-mini"
)

By default, get_caption uses a prompt validated in Lokmanoglu & Walter (2025), which instructs the model to describe the scene briefly, note (but not transcribe) any visible text, and name recognizable public figures without background context. This keeps captions consistent for downstream topic modeling.

Supports both OpenAI and Anthropic vision models, auto-detected from the model name:

# OpenAI
get_caption(mykey=os.environ["OPENAI_API_KEY"], path_in="images",
            captions_file="captions.csv", model="gpt-4o-mini")

# Anthropic (Claude)
get_caption(mykey=os.environ["ANTHROPIC_API_KEY"], path_in="images",
            captions_file="captions.csv", model="claude-haiku-4-5-20251001")

To override auto-detection, pass provider="openai" or provider="anthropic" explicitly.

To adapt captioning to a different domain or model, pass your own prompt:

get_caption(
    mykey="your-api-key",
    path_in="images",
    captions_file="captions_file.csv",
    model="gpt-4o-mini",
    prompt="Describe any protest signage, crowd size, and police presence visible in this image."
)

Note: different models can interpret the same instructions differently. If you switch models or providers, it’s worth re-piloting your prompt on a small sample first.

get_caption is resumable — it skips images already listed in captions_file (and skips hidden system files like .DS_Store), so an interrupted run can just be rerun to pick up where it left off.

License

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

Contributing

We welcome contributions! If you’d like to contribute:

  1. Fork the repository
  2. Create a feature branch:
git checkout -b feature-name
  1. Commit your changes:
git commit -m "Add new feature"
  1. Push to the branch:
git push origin feature-name
  1. Open a pull request

Repository Structure

vistopics/           # Python package
  __init__.py
  captioning.py
  extract_frames.py
  image_download.py
  reduce_frame.py
  video_scrape.py

paper/               # Paper replication code
  python/
    study1_videos.py       # Video processing for Study 1
    study2_images.py       # Image processing for Study 2
  R/
    study1_videos_lda.R    # LDA on video frame captions (Study 1)
    study1_transcripts_lda.R # LDA on transcripts (Study 1)
    study2_images_lda.R    # LDA on image captions (Study 2)

LICENSE
README.md

Paper Replication Code:

APA citation: Lokmanoglu, A. D., & Walter, D. (2025). Topic modeling of video and image data: A visual semantic unsupervised approach. Communication Methods and Measures. https://www.tandfonline.com/doi/abs/10.1080/19312458.2025.2549707

BibTeX citation:

@article{lokmanogluwalter2025topic,
  author       = {Lokmanoglu, A. D. and Walter, D.},
  title        = {Topic modeling of video and image data: A visual semantic unsupervised approach},
  journal      = {Communication Methods and Measures},
  year         = {2025},
  doi          = {10.1080/19312458.2025.2549707},
  url          = {https://www.tandfonline.com/doi/abs/10.1080/19312458.2025.2549707},
}

The paper/ folder contains all code and workflows for replicating the analyses in our studies.

Note: The paper code is a mix of R (for topic modeling, statistical analysis) and Python (for preprocessing and caption generation). You will need R ≥ 4.2 and see individual script headers for full package requirements.

Study 1 — Videos

Study 1 — Transcripts (LDA)

Study 2 — News Images

Data Availability

All datasets and additional materials needed to run the LDA analyses are available on OSF: https://osf.io/vhdaj/ (view-only)

Contact

If you have any questions or feedback, feel free to contact:

Ayse Lokmanoglu & Dror Walter

GitHub: https://github.com/aysedeniz09/VisTopics

Acknowledgments

The vistopics package incorporates and builds upon the work of the following projects and resources:

We thank the developers and maintainers of these tools for making their work publicly available and for their contributions to the open-source community.

This site is open source. Improve this page.