sensus

Sensory perception simulation for images and audio — apply color blindness, low vision, visual field defects, and hearing loss filters to ordinary photos and audio buffers. Built as a Rust crate so it can power accessibility demos, educational tools, and apps like universal-experience.

sensus (Latin) — "sense, perception, feeling".

Status

v0.5.0 — published on crates.io. All vision filters through Phase 4 (color vision, refraction, visual field, light/transparency, balance/vertigo, eye fatigue, and more) are implemented, plus 14 hearing filters (usable from the CLI via --audio). See docs/roadmap.md for the full phase tracker.

Filters

Vision

Additional vision filters (library Filter enum and CLI --filter): metamorphopsia (#55), contrast-sensitivity (#56), detail-loss (#57), teichopsia (#58), and flickering-stars (#59). The library function names use underscores (contrast_sensitivity, detail_loss, flickering_stars); the CLI flag names and the night-blindness / nyctalopia pair follow the kebab-case ↔ snake-case mapping clap derives.

Depth-aware refraction is also available CLI-side only via --filter myopia-depth / hyperopia-depth / depth-of-field combined with --depth, --mpo, or --portrait (#19).

Hearing (library + CLI)

14 hearing filters operate on audio buffers (#7–#9, #102–#104): hearing_loss, sudden_hearing_loss, noise_induced_hearing_loss, tinnitus, hyperacusis, misophonia, paracusis, amusia, dysmelodia, pitch_shift_semitones, diplacusis, auditory_processing_disorder (APD), meniere, and labyrinthitis. Each takes a sensus_core::hearing::AudioBuffer (f32 interleaved PCM) and returns one.

From the CLI, use --audio <in.wav> --hearing <filter> -o <out.wav> (WAV only). See CLI usage. From Rust, use sensus_core::apply_hearing / HearingFilter, or chain via AudioPipeline.

Composite experiences (Experience)

Some conditions span both vision and hearing (e.g. Ménière's disease = spinning vertigo + low-frequency hearing loss + low-pitched tinnitus). Because sensus is a pure, separate-buffer (image vs audio) library, Experience canonicalises which vision filter pairs with which hearing filter, so consumers (e.g. the universal-experience GUI) don't hard-code the combination: Experience::MENIERE, BPPV, VESTIBULAR_NEURITIS, LABYRINTHITIS. Each carries an Urgency classification for "see a doctor" prompts.

Each filter ships with a short note on when to see a doctor — sensus is designed both as an empathy / education tool and as an early-warning primer for symptoms worth taking seriously.

Install

cargo install sensus

This installs the sensus CLI binary. Pre-built binaries for Linux, macOS (Intel & Apple Silicon), and Windows are also attached to each GitHub Release.

CLI usage

# Phase 1: color vision deficiency simulation
sensus -i photo.png -o photo-deuteranopia.png --filter deuteranopia --strength 1.0
sensus -i photo.png -o photo-grayscale.png    --filter achromatopsia --strength 1.0
sensus -i photo.png -o photo-mild-protan.png  --filter protanopia    --strength 0.5

# Phase 2: focus / refraction (disk blur in linear sRGB)
sensus -i photo.png -o photo-myopia.png       --filter myopia        --strength 1.0
sensus -i photo.png -o photo-presbyopia.png   --filter presbyopia    --strength 0.7
# astigmatism with explicit cylinder axis (degrees, 0..=180; default 90)
sensus -i photo.png -o photo-astig.png        --filter astigmatism   --strength 1.0 --axis 90

# Phase 3: visual field defects and light conditions
sensus -i photo.png -o photo-glaucoma.png     --filter glaucoma      --strength 1.0
sensus -i photo.png -o photo-cataract.png     --filter cataract      --strength 0.8

# Pipeline: chain multiple filters in one pass
sensus -i photo.png -o out.png --filter deuteranopia --filter myopia --strength 1.0
sensus -i photo.png -o out.png --filter glaucoma --filter cataract --strength 0.7

# Pipe mode: read JPEG frames from stdin, write filtered frames to stdout (ffmpeg integration)
# --output is not required when --pipe is used
ffmpeg -i video.mp4 -f image2pipe -vcodec mjpeg - | \
    sensus --filter deuteranopia --pipe | \
    ffmpeg -f mjpeg -i - -c:v libx264 out.mp4

# Hearing: apply hearing filters to a WAV file (#105). WAV in / WAV out only.
sensus --audio voice.wav -o voice-hearing-loss.wav --hearing hearing-loss -s 1.0
sensus --audio voice.wav -o voice-tinnitus.wav     --hearing tinnitus     --freq 6000 -s 0.7
# Chain hearing filters and use the composite Ménière hearing side
sensus --audio voice.wav -o voice-meniere.wav      --hearing meniere      -s 0.8
sensus --audio voice.wav -o voice-chain.wav        --hearing hearing-loss tinnitus --freq 4000

Flags:

Per-filter parameter flags only affect their own filter; passing one to an unrelated single filter prints a warning and is otherwise ignored. Run sensus --help for the full list of filter names and flags.

Library usage

sensus-core is the pure-logic crate (no I/O). Take a DynamicImage in, get a DynamicImage out.

# Cargo.toml
[dependencies]
sensus-core = "0.5"

use image::DynamicImage;
use sensus_core::{apply, vision, Filter};

fn examples(img: DynamicImage) -> sensus_core::Result<()> {
    // Direct call (most ergonomic for a known filter):
    let _full   = vision::deuteranopia(img.clone(), 1.0)?;
    let _mild   = vision::deuteranopia(img.clone(), 0.5)?;
    let _gray   = vision::achromatopsia(img.clone(), 1.0)?;
    let _near   = vision::myopia(img.clone(), 1.0)?;
    let _astig  = vision::astigmatism(img.clone(), 0.5, 45.0)?; // axis in degrees

    // Or via the dispatching facade (handy when the filter is dynamic).
    // Filter-specific parameters travel in the enum variant, so `apply()`
    // honours them (e.g. the astigmatism axis below):
    let _shifted = apply(Filter::Protanopia, img.clone(), 1.0)?;
    let _astig2  = apply(Filter::Astigmatism { axis_deg: 45.0 }, img, 1.0)?;
    Ok(())
}

strength is clamped to [0.0, 1.0]. Filters in Phase 1 simulate color vision deficiency in linear sRGB space using the Machado 2009 model; achromatopsia uses the BT.709 photopic luminance. (BT.601 luma coefficients are designed for NTSC CRTs and are colorimetrically wrong for sRGB images.) Phase 2 (refraction) applies an optically correct disk blur in linear sRGB — radius derived from 0.5 × pupil_diameter × |D| (Smith–Helmholtz gives angular diameter, so the radius is half), min(W, H)-relative, edge-replicated borders. astigmatism is 1D directional blur (pure cylindrical lens / line spread function), not an elliptical disk — see docs/overview.md for the full derivation.

The same function signatures can be applied frame-by-frame for video, or chained together via sensus_core::pipeline.

Hearing filters

Hearing filters live in sensus_core::hearing and are dispatched via apply_hearing. They operate on audio buffers, not images. From the CLI they are reachable via --audio <in.wav> --hearing <filter> -o <out.wav> (WAV only); from Rust use the API below or chain them via AudioPipeline.

use sensus_core::{apply_hearing, hearing::AudioBuffer, HearingFilter};

fn deafen(buf: AudioBuffer) -> sensus_core::Result<AudioBuffer> {
    let muffled = apply_hearing(HearingFilter::HearingLoss, buf, 1.0)?;
    // Tinnitus and pitch shift carry their own parameters in the variant:
    let ringing = apply_hearing(HearingFilter::Tinnitus { freq_hz: 4000.0 }, muffled, 0.5)?;
    Ok(ringing)
}

GLSL shaders (host integration)

sensus_core::shaders ships the same vision effects as GLSL fragment shaders for hosts that render on the GPU (Flutter FragmentProgram, WebGL, etc.). Some shaders need resolution-dependent uniforms — e.g. photophobia, eye_strain, dry_eye, teichopsia, glaucoma, macular_degeneration, tunnel_vision, and the disk-blur refraction filters consume values such as uRadiusPx and uTexelSize (vec2(1.0/width, 1.0/height)). When using these shaders in an external host you must set those uniforms from the matching *_uniforms() helper (e.g. shaders::photophobia_uniforms(strength, width, height)); passing only strength will produce incorrect (scale-dependent) results. This is the contract universal-experience relies on.

Crates

License

MIT (c) 2026 kako-jun. See LICENSE.