API Reference

This page contains the API reference for CatVision.

Core Module

Core CatVisionFilter class implementation.

class catvision.core.CatVisionFilter[source]

Bases: SpectralMixin, SpatialMixin, TemporalMixin, MotionMixin, LowlightMixin, VisualizationMixin, ValidationMixin

Comprehensive cat vision emulation filter based on feline retinal biology.

This class implements biologically accurate computational filters that emulate feline visual perception, based on peer-reviewed research on cat retinal structure and visual characteristics.

Key characteristics implemented: - Vertical slit pupil (3:1 aspect ratio) - Enhanced blue-green sensitivity (~500nm peak) - Rod-dominated vision (25:1 rod/cone ratio) - Tapetum lucidum light reflection (30% enhancement) - Reduced color discrimination - Enhanced motion detection (1.8x sensitivity) - Wide field of view (200°×140°) - Reduced spatial acuity (1/6 human acuity) - Enhanced temporal processing (55Hz flicker fusion) - Horizontal motion bias (1.5x)

pupil_aspect_ratio

Vertical slit pupil aspect ratio (3:1)

Type:

float

rod_cone_ratio

Rod to cone ratio (25:1 vs human 20:1)

Type:

float

peak_wavelength

Peak spectral sensitivity wavelength (500nm)

Type:

int

tapetum_reflectance

Tapetum lucidum reflection factor (0.3)

Type:

float

visual_field_h

Horizontal field of view in degrees (200°)

Type:

int

visual_field_v

Vertical field of view in degrees (140°)

Type:

int

s_cone_peak

S-cone peak sensitivity wavelength (450nm)

Type:

int

l_cone_peak

L-cone peak sensitivity wavelength (556nm)

Type:

int

rod_peak

Rod peak sensitivity wavelength (498nm)

Type:

int

spatial_acuity_factor

Spatial acuity reduction factor (0.167)

Type:

float

foveal_acuity_cycles_per_degree

Peak acuity in cpd (3.0)

Type:

float

flicker_fusion_threshold

Flicker fusion threshold in Hz (55)

Type:

int

temporal_sensitivity_peak

Peak temporal sensitivity in Hz (10)

Type:

int

motion_sensitivity

Motion detection enhancement (1.8)

Type:

float

horizontal_motion_bias

Horizontal motion bias (1.5)

Type:

float

Example

>>> from catvision import CatVisionFilter
>>> import cv2
>>>
>>> # Initialize the filter
>>> cat_filter = CatVisionFilter()
>>>
>>> # Load an image
>>> image = cv2.imread('input.jpg')
>>>
>>> # Apply cat vision transformation
>>> result = cat_filter.apply_cat_vision(image, use_biological_accuracy=True)
>>>
>>> # Save the result
>>> cv2.imwrite('output.jpg', result)
>>>
>>> # Visualize spectral sensitivity
>>> cat_filter.plot_spectral_sensitivity_curves()
>>>
>>> # Validate biological accuracy
>>> validation = cat_filter.validate_biological_accuracy([image])
>>> print(f"Overall accuracy: {validation['overall_accuracy_score']:.2%}")
__init__()[source]

Initialize cat vision filter with biologically accurate parameters.

All parameters are based on peer-reviewed research on cat vision and retinal physiology.

apply_cat_vision(image: ndarray, previous_frame: ndarray | None = None, kernel_size: int = 15, use_biological_accuracy: bool = True) → ndarray[source]

Apply complete cat vision pipeline with enhanced biological accuracy.

This is the main method for applying the cat vision transformation. It processes the input image through multiple stages to simulate how a cat would perceive the scene.

Pipeline stages (with use_biological_accuracy=True): 1. Spatial field transformation (wide FOV) 2. Pupil filter (vertical slit) 3. Spectral sensitivity correction 4. Spatial acuity reduction 5. Rod dominance effects 6. Tapetum lucidum enhancement

Parameters:

  • image – Input image in BGR format (OpenCV convention)

  • previous_frame – Previous frame for motion detection (optional)

  • kernel_size – Size of pupil kernel (default: 15, should be odd)

  • use_biological_accuracy – Use new biologically accurate methods (True) vs legacy methods (False)

Returns:

Cat vision processed image in BGR format

Example

>>> cat_filter = CatVisionFilter()
>>> image = cv2.imread('input.jpg')
>>> result = cat_filter.apply_cat_vision(image, use_biological_accuracy=True)
>>> cv2.imwrite('cat_vision.jpg', result)
apply_cat_vision_to_sequence(frame_sequence: List[ndarray], fps: int = 30, use_biological_accuracy: bool = True) → List[ndarray][source]

Apply cat vision processing to a sequence of frames with temporal processing.

This method is designed for video processing and includes temporal and motion detection enhancements that require multiple frames.

Parameters:

  • frame_sequence – List of consecutive frames in BGR format

  • fps – Frames per second of the input sequence

  • use_biological_accuracy – Use enhanced biological methods

Returns:

Processed frame sequence

Example

>>> cat_filter = CatVisionFilter()
>>> frames = [cv2.imread(f'frame_{i:04d}.jpg') for i in range(100)]
>>> processed = cat_filter.apply_cat_vision_to_sequence(frames, fps=30)
>>> for i, frame in enumerate(processed):
...     cv2.imwrite(f'cat_frame_{i:04d}.jpg', frame)
get_filter_parameters() → Dict[source]

Get current filter parameters for documentation and reproducibility.

Returns:

Dictionary of all filter parameters with biological values

Example

>>> cat_filter = CatVisionFilter()
>>> params = cat_filter.get_filter_parameters()
>>> print(f"Rod/cone ratio: {params['rod_cone_ratio']}")
>>> print(f"Spatial acuity: {params['spatial_acuity_factor']}")
save_parameters(filepath: str | Path) → None[source]

Save filter parameters to JSON file.

Parameters:

filepath – Path to save parameters

Example

>>> cat_filter = CatVisionFilter()
>>> cat_filter.save_parameters('cat_vision_params.json')

Spectral Processing

Spectral sensitivity processing for cat vision simulation.

class catvision.spectral.SpectralMixin[source]

Bases: object

Mixin class for spectral sensitivity processing methods.

Implements biologically accurate spectral sensitivity curves based on cat photoreceptor characteristics (S-cones, L-cones, and rods).

apply_spectral_sensitivity_curves(image: ndarray) → ndarray[source]

Apply biological spectral sensitivity curves instead of simple RGB weights.

This method maps RGB channels to the biological spectral sensitivity of cat photoreceptors, accounting for the rod-dominated vision (25:1 rod/cone ratio).

Parameters:

image – Input image in BGR format (OpenCV convention)

Returns:

Spectrally corrected image with cat-like color perception

adjust_color_sensitivity(image: ndarray) → ndarray[source]

Adjust color sensitivity to match cat vision (legacy method).

Cats have peak sensitivity around 500nm (blue-green) and reduced red sensitivity compared to humans. This is a simplified legacy method for backward compatibility.

Parameters:

image – Input image in BGR format

Returns:

Color-adjusted image

Spatial Processing

Spatial processing methods for cat vision simulation.

class catvision.spatial.SpatialMixin[source]

Bases: object

Mixin class for spatial processing methods.

Implements cat-specific spatial characteristics including: - Vertical slit pupil (3:1 aspect ratio) - Reduced spatial acuity (1/6 human acuity) - Wide-angle field of view (200°×140°) - Center-surround acuity mapping

create_pupil_kernel(kernel_size: int = 15) → ndarray[source]

Create vertical slit pupil convolution kernel.

Cats have a distinctive vertical slit pupil with a 3:1 aspect ratio, which affects light distribution and depth of field.

Parameters:

kernel_size – Size of the kernel (should be odd)

Returns:

Normalized convolution kernel representing cat pupil

apply_pupil_filter(image: ndarray, kernel_size: int = 15) → ndarray[source]

Apply vertical slit pupil convolution filter.

Parameters:

  • image – Input image

  • kernel_size – Size of pupil kernel

Returns:

Pupil-filtered image

simulate_spatial_acuity_reduction(image: ndarray, acuity_factor: float | None = None) → ndarray[source]

Simulate cat spatial acuity reduction using frequency domain filtering.

Cats have approximately 1/6 the spatial acuity of humans, corresponding to visual acuity of about 20/100 to 20/200 in human terms.

Parameters:

  • image – Input image

  • acuity_factor – Acuity reduction factor (default: 0.167 = 1/6 human acuity)

Returns:

Spatially filtered image

apply_spatial_field_transformation(image: ndarray, fov_horizontal: int = 200, fov_vertical: int = 140) → ndarray[source]

Apply wide-angle peripheral vision transformation.

Cats have a wider field of view than humans (200°×140° vs 180°×120°), with enhanced peripheral vision but reduced central acuity.

Parameters:

  • image – Input image

  • fov_horizontal – Horizontal field of view in degrees (default: 200°)

  • fov_vertical – Vertical field of view in degrees (default: 140°)

Returns:

Transformed image with cat-like field of view

Temporal Processing

Temporal processing methods for cat vision simulation.

class catvision.temporal.TemporalMixin[source]

Bases: object

Mixin class for temporal processing methods.

Implements cat temporal characteristics: - Enhanced flicker fusion threshold (55Hz vs human 24Hz) - Peak temporal sensitivity at 10Hz - Enhanced temporal frequency response

model_temporal_processing(frame_sequence: List[ndarray], fps: int = 30) → List[ndarray][source]

Model cat temporal processing with enhanced flicker fusion threshold.

Cats can detect flicker up to 55Hz compared to humans at ~24Hz, making them more sensitive to rapid changes and motion.

Parameters:

  • frame_sequence – List of consecutive frames

  • fps – Frames per second of the input sequence

Returns:

Temporally processed frame sequence

Motion Processing

Motion detection methods for cat vision simulation.

class catvision.motion.MotionMixin[source]

Bases: object

Mixin class for motion detection methods.

Implements cat-specific motion detection characteristics: - Enhanced motion sensitivity (1.8x human) - Horizontal motion bias (1.5x) - Optical flow-based motion detection

enhanced_motion_detection(frame_sequence: List[ndarray], flow_method: str = 'lucas_kanade') → List[ndarray][source]

Enhanced motion detection with optical flow and directional sensitivity.

Cats excel at detecting motion, particularly horizontal motion, which is critical for hunting prey.

Parameters:

  • frame_sequence – List of consecutive frames

  • flow_method – Optical flow method (‘lucas_kanade’ or ‘farneback’)

Returns:

Motion-enhanced frame sequence

enhance_motion_detection(image: ndarray, previous_frame: ndarray | None = None) → ndarray[source]

Enhance motion detection capabilities (legacy method).

Rod cell specialization for motion detection.

Parameters:

  • image – Current frame

  • previous_frame – Previous frame for motion detection

Returns:

Motion-enhanced image

Low-light Processing

Low-light vision methods for cat vision simulation.

class catvision.lowlight.LowlightMixin[source]

Bases: object

Mixin class for low-light vision methods.

Implements cat-specific low-light adaptations: - Tapetum lucidum light reflection (30% reflectance) - Rod-dominated vision (25:1 rod/cone ratio) - Enhanced contrast in low-light - Reduced color discrimination

apply_tapetum_effect(image: ndarray, brightness_threshold: float = 0.3) → ndarray[source]

Simulate tapetum lucidum light reflection effect.

The tapetum lucidum is a reflective layer behind the retina that reflects light back through the retina, enhancing low-light vision performance by approximately 30%.

Parameters:

  • image – Input image

  • brightness_threshold – Threshold for low-light enhancement (0.0-1.0)

Returns:

Image with tapetum effect applied

simulate_rod_dominance(image: ndarray) → ndarray[source]

Simulate effects of rod-dominated vision (25:1 rod/cone ratio).

Rod cells are responsible for: - Low-light vision - Motion detection - Peripheral vision - Reduced color discrimination

Cats have a much higher rod-to-cone ratio than humans (25:1 vs 20:1), resulting in excellent night vision but reduced color perception.

Parameters:

image – Input image

Returns:

Image with rod dominance effects

Visualization

Visualization utilities for cat vision filter.

class catvision.visualization.VisualizationMixin[source]

Bases: object

Mixin class for visualization methods.

Provides comprehensive visualization tools for understanding cat vision characteristics and filter behavior.

plot_spectral_sensitivity_curves(save_path: str | None = None) → None[source]

Visualize cat photoreceptor spectral sensitivity curves.

Displays the spectral sensitivity of S-cones, L-cones, and rods, along with RGB wavelength markers.

Parameters:

save_path – Optional path to save the plot

visualize_spatial_acuity_map(image_size: Tuple[int, int], save_path: str | None = None) → None[source]

Visualize spatial acuity mapping across the visual field.

Shows how spatial acuity decreases from center to periphery, characteristic of cat vision.

Parameters:

  • image_size – (height, width) of the reference image

  • save_path – Optional path to save the visualization

demonstrate_temporal_frequency_response(save_path: str | None = None) → None[source]

Demonstrate cat temporal frequency response characteristics.

Shows the enhanced temporal sensitivity compared to humans, particularly the higher flicker fusion threshold.

Parameters:

save_path – Optional path to save the plot

visualize_pupil_kernel(kernel_size: int = 15, save_path: str | None = None) → None[source]

Visualize the pupil kernel for validation.

Shows the vertical slit pupil convolution kernel with 3:1 aspect ratio.

Parameters:

  • kernel_size – Size of kernel to visualize

  • save_path – Optional path to save visualization

compare_motion_detection_sensitivity(test_video_frames: List[ndarray], save_path: str | None = None) → None[source]

Compare motion detection sensitivity between cat and human-like processing.

Demonstrates the enhanced motion detection capabilities of cat vision.

Parameters:

  • test_video_frames – List of video frames for analysis

  • save_path – Optional path to save the comparison plot

Utilities

Utility functions for cat vision filter.

catvision.utils.load_image(image_path: str | Path) → ndarray | None[source]

Load an image from file.

Parameters:

image_path – Path to the image file

Returns:

Image as numpy array in BGR format, or None if loading fails

catvision.utils.save_image(image: ndarray, output_path: str | Path) → bool[source]

Save an image to file.

Parameters:

  • image – Image as numpy array

  • output_path – Path to save the image

Returns:

True if successful, False otherwise

catvision.utils.validate_image(image: ndarray) → bool[source]

Validate that an image is in the correct format.

Parameters:

image – Image to validate

Returns:

True if valid, False otherwise

catvision.utils.normalize_image(image: ndarray) → ndarray[source]

Normalize image to 0-255 range as uint8.

Parameters:

image – Input image

Returns:

Normalized image

catvision.utils.create_test_image(size: tuple = (480, 640), pattern: str = 'checkerboard') → ndarray[source]

Create a test image for validation and testing.

Parameters:

  • size – Image size as (height, width)

  • pattern – Pattern type (‘checkerboard’, ‘gradient’, ‘color_bars’)

Returns:

Test image as numpy array

Validation

Validation methods for biological accuracy verification.

class catvision.validation.ValidationMixin[source]

Bases: object

Mixin class for validation methods.

Validates filter outputs against published biological data on cat vision characteristics.

validate_biological_accuracy(test_images: List[ndarray], ground_truth_data: Dict | None = None) → Dict[source]

Validate biological accuracy against published cat vision characteristics.

Compares filter behavior with peer-reviewed research on: - Spectral sensitivity curves - Spatial acuity measurements - Temporal response characteristics - Motion detection capabilities

Parameters:

  • test_images – List of test images for validation

  • ground_truth_data – Optional ground truth data for comparison

Returns:

Validation results dictionary with accuracy scores