ScopeOn

GPU-accelerated image and video analysis scope for Python, leveraging CuPy and CUDA for real-time video processing.

Features

• High-Speed Processing: Optimized with CuPy's CUDA RawKernel for extremely fast video analysis
• Waveform Scope: Detailed analysis of brightness distribution with parade and overlay modes
• VectorScope: Analysis of color distribution and saturation
• Histogram: RGB histogram visualization with vertical, horizontal, and overlay layouts
• ScopeGrid: Flexible image composition utility (grid_2x2, hstack, vstack)

⚠️ Breaking Changes (v2.0.0)

All scope outputs are now cp.ndarray (CuPy arrays) only.

• Previous behavior (v1.x): Scopes returned the same array type as input (np.ndarray → np.ndarray, cp.ndarray → cp.ndarray)
• New behavior (v2.0.0+): All scopes always return cp.ndarray, regardless of input type
• Reason: Eliminates type-branching overhead and enforces GPU-accelerated processing

Migration Guide:

import pixtreme as px
from scopeon import Waveform

image = px.imread("image.jpg")  # May return np.ndarray or cp.ndarray
result = waveform.get(image)     # Always returns cp.ndarray (v2.0.0+)

# If you need NumPy array, convert explicitly:
result_np = px.to_numpy(result)  # cp.ndarray → np.ndarray

Requirements

• Python: 3.12 or higher
• GPU: NVIDIA with CUDA compute capability ≥6.0
• CUDA: Toolkit 12.x
• Dependencies: CuPy, NumPy, OpenCV, pixtreme

Installation

Install from PyPI:

pip install scopeon

Or install from source:

git clone https://github.com/sync-dev-org/scopeon.git
cd scopeon
pip install -e .

API

• Waveform: Brightness distribution scope
• VectorScope: Color distribution and saturation scope
• Histogram: RGB histogram visualization scope
• ScopeGrid: Image composition utility

Usage

Basic Usage (4-Panel Layout)

import pixtreme as px
from scopeon import Waveform, VectorScope, Histogram, ScopeGrid

# 1. Load image (using pixtreme)
image = px.imread("image.jpg")  # BGR format, typically float32
image = px.to_float32(image)  # Failsafe: ensure float32

# 2. Draw each scope (all return cp.ndarray in v2.0.0+)
waveform = Waveform()
vectorscope = VectorScope()
histogram = Histogram()

wf = waveform.get(image)      # Returns cp.ndarray
vs = vectorscope.get(image)   # Returns cp.ndarray
hist = histogram.get(image)   # Returns cp.ndarray

# 3. Compose grid
result = ScopeGrid.grid_2x2(  # Returns cp.ndarray
    top_left=image,
    top_right=wf,
    bottom_left=vs,
    bottom_right=hist
)

# 4. Display (pixtreme handles both np.ndarray and cp.ndarray)
px.imshow("result", result)
px.waitkey(0)
px.destroy_all_windows()

# If you need NumPy array for other libraries:
result_np = px.to_numpy(result)  # Convert cp.ndarray → np.ndarray

Using Individual Scopes

import pixtreme as px
from scopeon import Waveform, Histogram

# Waveform only (returns cp.ndarray)
image = px.imread("image.jpg")
image = px.to_float32(image)  # Failsafe

wf = Waveform(colorize=True, show_indicator=True)
waveform_image = wf.get(image, mode="parade")  # cp.ndarray

px.imshow("waveform", waveform_image)
px.waitkey(0)

# Histogram only (returns cp.ndarray)
hist = Histogram(layout="overlay", show_indicator=True, num_bins=512)
histogram_image = hist.get(image)  # cp.ndarray

px.imshow("histogram", histogram_image)
px.waitkey(0)

# Convert to NumPy if needed for non-GPU libraries:
import numpy as np
waveform_np = px.to_numpy(waveform_image)   # cp.ndarray → np.ndarray
histogram_np = px.to_numpy(histogram_image)  # cp.ndarray → np.ndarray

License

ScopeOn is released under the MIT License. For more details, see the LICENSE file.

Authors

Taichi Okada (@minamikik)

Acknowledgments

sync.dev