Struct HistogramExtractor 

pub struct HistogramExtractor { /* private fields */ }

Extracts per-channel color histograms at configurable frame intervals.

Decodes the input video via VideoDecoder with RGB24 output conversion so that histogram accumulation is a simple one-pass loop with no additional format dispatch. FFmpeg’s histogram filter is deliberately not used because it produces video output rather than structured data.

Examples

use ff_analysis::HistogramExtractor;

let histograms = HistogramExtractor::new("video.mp4")
    .interval_frames(30)
    .run()?;

for h in &histograms {
    println!("Frame at {:?}: r[255]={}", h.timestamp, h.r[255]);
}

Implementations

impl HistogramExtractor

pub fn new(input: impl AsRef<Path>) -> Self

Creates a new extractor for the given video file.

The default sampling interval is every frame (interval_frames = 1). Call interval_frames to sample less frequently.

Examples found in repository

examples/histogram.rs (line 89)

fn main() {
    let mut args = std::env::args().skip(1);
    let mut input = None::<String>;
    let mut interval_frames = 30u32;

    while let Some(flag) = args.next() {
        match flag.as_str() {
            "--input" | "-i" => input = Some(args.next().unwrap_or_default()),
            "--interval" | "-n" => {
                let raw = args.next().unwrap_or_default();
                interval_frames = raw.parse().unwrap_or_else(|_| {
                    eprintln!("Invalid interval: {raw}");
                    process::exit(1);
                });
            }
            other => {
                eprintln!("Unknown flag: {other}");
                process::exit(1);
            }
        }
    }

    let input = input.unwrap_or_else(|| {
        eprintln!("Usage: histogram --input <video> [--interval <frames>]");
        process::exit(1);
    });

    println!("Extracting color histograms from: {input}");
    println!("Sampling every {interval_frames} frame(s)");
    println!();

    let histograms: Vec<FrameHistogram> = HistogramExtractor::new(&input)
        .interval_frames(interval_frames)
        .run()
        .unwrap_or_else(|e| {
            eprintln!("Error: {e}");
            process::exit(1);
        });

    println!("Extracted {} histogram(s).", histograms.len());
    println!();
    println!(
        "  {:^6}  {:^8}  {:^6}  {:^6}  {:^6}  {:^6}  {:^11}  {:^11}  {:^11}",
        "Index", "Time (s)", "Mean R", "Mean G", "Mean B", "Luma", "Dom. R", "Dom. G", "Dom. B"
    );
    println!("{}", "-".repeat(95));

    let display_count = histograms.len().min(30);
    for (i, h) in histograms.iter().take(display_count).enumerate() {
        print_histogram_summary(i, h);
    }
    if histograms.len() > display_count {
        println!("  … ({} more histograms)", histograms.len() - display_count);
    }
}

pub fn interval_frames(self, n: u32) -> Self

Sets the frame sampling interval.

A value of N means one histogram is computed per N decoded frames. For example, interval_frames(30) on a 30 fps video yields roughly one histogram per second.

Passing 0 causes run to return AnalysisError::Failed.

Default: 1 (every frame).

Examples found in repository

examples/histogram.rs (line 90)

fn main() {
    let mut args = std::env::args().skip(1);
    let mut input = None::<String>;
    let mut interval_frames = 30u32;

    while let Some(flag) = args.next() {
        match flag.as_str() {
            "--input" | "-i" => input = Some(args.next().unwrap_or_default()),
            "--interval" | "-n" => {
                let raw = args.next().unwrap_or_default();
                interval_frames = raw.parse().unwrap_or_else(|_| {
                    eprintln!("Invalid interval: {raw}");
                    process::exit(1);
                });
            }
            other => {
                eprintln!("Unknown flag: {other}");
                process::exit(1);
            }
        }
    }

    let input = input.unwrap_or_else(|| {
        eprintln!("Usage: histogram --input <video> [--interval <frames>]");
        process::exit(1);
    });

    println!("Extracting color histograms from: {input}");
    println!("Sampling every {interval_frames} frame(s)");
    println!();

    let histograms: Vec<FrameHistogram> = HistogramExtractor::new(&input)
        .interval_frames(interval_frames)
        .run()
        .unwrap_or_else(|e| {
            eprintln!("Error: {e}");
            process::exit(1);
        });

    println!("Extracted {} histogram(s).", histograms.len());
    println!();
    println!(
        "  {:^6}  {:^8}  {:^6}  {:^6}  {:^6}  {:^6}  {:^11}  {:^11}  {:^11}",
        "Index", "Time (s)", "Mean R", "Mean G", "Mean B", "Luma", "Dom. R", "Dom. G", "Dom. B"
    );
    println!("{}", "-".repeat(95));

    let display_count = histograms.len().min(30);
    for (i, h) in histograms.iter().take(display_count).enumerate() {
        print_histogram_summary(i, h);
    }
    if histograms.len() > display_count {
        println!("  … ({} more histograms)", histograms.len() - display_count);
    }
}

pub fn run(self) -> Result<Vec<FrameHistogram>, AnalysisError>

Runs histogram extraction and returns one FrameHistogram per sampled frame.

Frames are decoded as RGB24 internally; all pixel format conversion is handled by FFmpeg’s software scaler.

Errors

• AnalysisError::Failed — interval_frames is 0, the input file is not found, or a decode error occurs.
• Any ff_decode::DecodeError propagated from VideoDecoder, wrapped in AnalysisError::Decode.

Examples found in repository

examples/histogram.rs (line 91)

fn main() {
    let mut args = std::env::args().skip(1);
    let mut input = None::<String>;
    let mut interval_frames = 30u32;

    while let Some(flag) = args.next() {
        match flag.as_str() {
            "--input" | "-i" => input = Some(args.next().unwrap_or_default()),
            "--interval" | "-n" => {
                let raw = args.next().unwrap_or_default();
                interval_frames = raw.parse().unwrap_or_else(|_| {
                    eprintln!("Invalid interval: {raw}");
                    process::exit(1);
                });
            }
            other => {
                eprintln!("Unknown flag: {other}");
                process::exit(1);
            }
        }
    }

    let input = input.unwrap_or_else(|| {
        eprintln!("Usage: histogram --input <video> [--interval <frames>]");
        process::exit(1);
    });

    println!("Extracting color histograms from: {input}");
    println!("Sampling every {interval_frames} frame(s)");
    println!();

    let histograms: Vec<FrameHistogram> = HistogramExtractor::new(&input)
        .interval_frames(interval_frames)
        .run()
        .unwrap_or_else(|e| {
            eprintln!("Error: {e}");
            process::exit(1);
        });

    println!("Extracted {} histogram(s).", histograms.len());
    println!();
    println!(
        "  {:^6}  {:^8}  {:^6}  {:^6}  {:^6}  {:^6}  {:^11}  {:^11}  {:^11}",
        "Index", "Time (s)", "Mean R", "Mean G", "Mean B", "Luma", "Dom. R", "Dom. G", "Dom. B"
    );
    println!("{}", "-".repeat(95));

    let display_count = histograms.len().min(30);
    for (i, h) in histograms.iter().take(display_count).enumerate() {
        print_histogram_summary(i, h);
    }
    if histograms.len() > display_count {
        println!("  … ({} more histograms)", histograms.len() - display_count);
    }
}