Vision Token Calculator

A Python tool for calculating the number of tokens generated when processing images with Vision Language Models (VLMs).

Quick Start

pip install vt-calc
vt-calc --size 1920 1080                    # Calculate tokens for 1920x1080 image
vt-calc --image photo.jpg -m qwen2.5-vl     # Calculate tokens for an image
vt-calc --compare all --size 1920 1080      # Compare all models

Features

Calculate image/video tokens for VLMs
Multi-model comparison - Compare token counts across multiple models
Support both existing images and dummy images
Support remote images via URL (http/https)
Simple command line interface (CLI)

Installation

Option 1: PyPI (recommended)

pip install vt-calc

Option 2: From source (editable for development)

pip install -e .

Usage

Basic Commands

# Single image
vt-calc --image path/to/your/image.jpg

# Image from URL
vt-calc --image https://example.com/image.jpg

# Directory (batch processing)
vt-calc --image path/to/your/images_dir

# Dummy image with specific dimensions (Height x Width)
vt-calc --size 1920 1080

# Choose a model (default: qwen2.5-vl)
vt-calc --image photo.jpg -m internvl3

Video Processing

# Calculate tokens for a video file
vt-calc --video path/to/video.mp4 -m qwen2.5-vl

# Specify frame sampling rate (FPS)
vt-calc --video video.mp4 --fps 2.0

# Limit maximum number of frames
vt-calc --video video.mp4 --max-frames 100

Model Comparison

# Compare specific models (comma-separated)
vt-calc --image photo.jpg --compare qwen2.5-vl,internvl3,llava

# Compare all supported models
vt-calc --size 1920 1080 --compare all

# Compare models for video
vt-calc --video video.mp4 --compare qwen2.5-vl,llava-next --fps 2.0

CLI Options

Option	Short	Description	Default
`--image`	`-i`	Path to image file, directory, or URL	-
`--video`	`-v`	Path to video file	-
`--size`	`-s`	Create dummy image (HEIGHT WIDTH)	-
`--model-name`	`-m`	Model name to use	`qwen2.5-vl`
`--compare`	`-c`	Compare models (comma-separated or `all`)	-
`--fps`	-	Frames per second for video sampling	-
`--max-frames`	-	Maximum frames to extract from video	-
`--duration`	-	Duration in seconds (dummy video)	-

Supported input formats: .jpg, .jpeg, .png, .webp (case-insensitive)

Example Output

Single Image Analysis

Using dummy image: 1920 x 1080
                        ╔══════════════════════════════╗
                        ║ VISION TOKEN ANALYSIS REPORT ║
                        ╚══════════════════════════════╝
╭───────────────────────────────── MODEL INFO ─────────────────────────────────╮
│   Model Name                deepseek-ocr-tiny                                │
│   Processing Method         Native Resolution                                │
╰──────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────── IMAGE INFO ─────────────────────────────────╮
│   Source                    Dummy image (H×W): 1920×1080                     │
│   Original Size (H×W)       1920×1080                                        │
│   Resized Size (H×W)        512×512                                          │
╰──────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────── PATCH INFO ─────────────────────────────────╮
│   Patch Size (ViT)          16                                               │
│   Patch Grid (H×W)          32×32                                            │
│   Total Patches             1024                                             │
╰──────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────────────── TOKEN INFO ─────────────────────────────────╮
│   Image Token (<image>)     64                                               │
│   Image Newline Token       8                                                │
│   (<image_newline>)                                                          │
│   Image Separator Token     1                                                │
│   (<image_separator>)                                                        │
│   Total Image Tokens        73                                               │
│   Pixels per Token          3591.0 px/token                                  │
╰──────────────────────────────────────────────────────────────────────────────╯
╭──────────────────────────────── TOKEN FORMAT ────────────────────────────────╮
│          (<image>*8 + <image_newline>) * 8 + <image_seperator> = 73          │
╰──────────────────────────────────────────────────────────────────────────────╯

Model Comparison

Comparing models for dummy image (H×W): 1920×1080

                           ╔════════════════════════╗
                           ║ IMAGE MODEL COMPARISON ║
                           ╚════════════════════════╝
                          Dummy image (H×W): 1920×1080
                          Resolution (H×W): 1920×1080

                                  Token Comparison
╭────────┬─────────────────────┬────────────┬────────────┬──────────────────┬────────╮
│  Rank  │ Model               │     Tokens │   px/token │ Efficiency       │ Status │
├────────┼─────────────────────┼────────────┼────────────┼──────────────────┼────────┤
│  🥇 1  │ deepseek-ocr-tiny   │         73 │     3591.0 │ █████████░ Best  │   ✓    │
│  🥈 2  │ deepseek-ocr-small  │        111 │     3690.1 │ █████████░       │   ✓    │
│  🥉 3  │ deepseek-ocr-base   │        273 │     3840.9 │ █████████░       │   ✓    │
│   4    │ deepseek-ocr-large  │        421 │     3891.7 │ █████████░       │   ✓    │
│   5    │ llava               │        576 │      196.0 │ █████████░       │   ✓    │
│   6    │ deepseek-ocr-gundam │      1,113 │      942.1 │ ████████░░       │   ✓    │
│   7    │ llava-next          │      1,968 │      129.1 │ ███████░░░       │   ✓    │
│   8    │ internvl3           │      2,306 │      696.3 │ ██████░░░░       │   ✓    │
│   9    │ qwen2-vl            │      2,693 │      783.4 │ ██████░░░░       │   ✓    │
│   10   │ qwen2.5-vl          │      2,693 │      783.4 │ ██████░░░░       │   ✓    │
│   11   │ llava-onevision     │      7,317 │      283.4 │ ░░░░░░░░░░       │   ✓    │
│   12   │ phi4-multimodal     │      7,553 │      744.0 │ ░░░░░░░░░░       │   ✓    │
╰────────┴─────────────────────┴────────────┴────────────┴──────────────────┴────────╯

╭────────────────────────────────── Summary ───────────────────────────────────╮
│ Best: deepseek-ocr-tiny (73 tokens)                                          │
│ Worst: phi4-multimodal (7,553 tokens)                                        │
│ Potential Savings: 7,480 tokens (99.0%)                                      │
╰──────────────────────────────────────────────────────────────────────────────╯

Supported Models

Model	Option	Image	Video
Qwen2-VL	`qwen2-vl`	✓	✓
Qwen2.5-VL	`qwen2.5-vl`	✓	✓
Qwen3-VL	`qwen3-vl`	✓	✓
LLaVA	`llava`	✓	✓
LLaVA-NeXT	`llava-next`	✓
LLaVA-OneVision	`llava-onevision`	✓	✓
InternVL3	`internvl3`	✓	✓
DeepSeek-OCR (tiny)	`deepseek-ocr-tiny`	✓
DeepSeek-OCR (small)	`deepseek-ocr-small`	✓
DeepSeek-OCR (base)	`deepseek-ocr-base`	✓
DeepSeek-OCR (large)	`deepseek-ocr-large`	✓
DeepSeek-OCR (gundam)	`deepseek-ocr-gundam`	✓
Phi-4-Multimodal	`phi4-multimodal`	✓

License

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

Metadata

Release files for vt-calc 0.0.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vt-calc 0.0.4
File	Size	Uploaded
vt_calc-0.0.4.tar.gz	36.4 kB	Jan 11, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for vt-calc 0.0.4
File	Interpreter	ABI	Platform	Reset
vt_calc-0.0.4-py3-none-any.whl 30.6 kB Jan 11, 2026	Python 3	none	any	Details

Total release size: 67.0 kB

Release files / vt_calc-0.0.4.tar.gz

Download URL	vt_calc-0.0.4.tar.gz
Size	36.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`84db0d5228e99395292d259840a54cca20f5a397933e8060ef3cdcfc87b92383`
BLAKE2b-256 checksum How to use checksums	`16b96c4077168d147a03a812152832da8b65b58e43454ae458e51d2e2604e139`
Upload date	Jan 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.10.12`

Release files / vt_calc-0.0.4-py3-none-any.whl

Download URL	vt_calc-0.0.4-py3-none-any.whl
Size	30.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`723f342d40e350ccaa51d27182fe53d4fd14e068bba2ef0e08fc98d6cd5f8bae`
BLAKE2b-256 checksum How to use checksums	`c0b20bee98f8b98430f4ee577e4f8d1b21326959cddd66b351512957947cd235`
Upload date	Jan 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.10.12`