High Definition Image Manipulator

Repository

I built HDIM (High Definition Image Manipulator) to bring a modern, non-destructive image editing experience directly to the terminal. Built in Rust using Ratatui, the application leverages 24-bit TrueColor half-block rendering to display high-detail image previews in terminal viewports while supporting real-time perceptual color adjustments, EXIF metadata extraction, and a complete undo/redo history stack.

Half-Block Viewport Mapping & Color Sampling

To render detailed images within standard terminal constraints, HDIM maps each terminal character cell to two vertically stacked pixels using half-block characters (▀ / ▄). The View struct calculates scale ratios between source image pixels and terminal rows, while map_to_source locates the top and bottom half-block regions. The get_average_rgb function then calculates the mean RGB color for each region to deliver smooth downscaling across dynamic terminal grid sizes.

1pub fn map_to_source(&self, x: u32, y: u32, x_ratio: f32, y_ratio: f32) -> (u32, u32, u32) {
2    let source_pixel_x = self.source_x + (x as f32 * x_ratio) as u32;
3    let source_pixel_y_top = self.source_y + (y as f32 * y_ratio) as u32;
4    let source_pixel_y_bottom = source_pixel_y_top + (y_ratio / 2.0).round().max(1.0) as u32;
5    (source_pixel_x, source_pixel_y_top, source_pixel_y_bottom)
6}
7
8pub fn get_average_rgb(
9    image: &DynamicImage,
10    start_x: u32,
11    start_y: u32,
12    width: u32,
13    height: u32,
14) -> [u8; 3] {
15    let (image_width, image_height) = image.dimensions();
16    let mut r_total: u64 = 0;
17    let mut g_total: u64 = 0;
18    let mut b_total: u64 = 0;
19    let mut count: u64 = 0;
20
21    let end_y = (start_y + height).min(image_height);
22    let end_x = (start_x + width).min(image_width);
23
24    for pixel_y in start_y..end_y {
25        for pixel_x in start_x..end_x {
26            let pixel = image.get_pixel(pixel_x, pixel_y);
27            r_total += pixel[0] as u64;
28            g_total += pixel[1] as u64;
29            b_total += pixel[2] as u64;
30            count += 1;
31        }
32    }
33
34    if count == 0 {
35        return [0, 0, 0];
36    }
37
38    [
39        (r_total / count) as u8,
40        (g_total / count) as u8,
41        (b_total / count) as u8,
42    ]
43}

Perceptually Uniform Color Adjustments

Instead of performing naive RGB arithmetic which can cause color clipping, image processing functions convert pixels into perceptual color spaces like Lch using the palette crate. The apply_brightness function transforms RGB channels into Lch representations, modifies the lightness (l) channel uniformly within valid bounds [0, 100], and converts the result back to sRGB to ensure natural contrast shifts during editing.

1pub fn apply_brightness(image: &DynamicImage, value: f32) -> DynamicImage {
2    let mut cloned_image = image.clone();
3    let factor = value * 0.5; // Map -100..100 to -50..50 (Lch 'l' is 0-100)
4
5    for (x, y, pixel) in cloned_image.to_rgba8().enumerate_pixels() {
6        let srgb = Srgb::new(
7            pixel[0] as f32 / 255.0,
8            pixel[1] as f32 / 255.0,
9            pixel[2] as f32 / 255.0,
10        );
11
12        let mut lch: Lch = Lch::from_color(srgb);
13        lch.l += factor;
14        lch.l = lch.l.clamp(0.0, 100.0); // Clamp L to its valid range
15
16        let new_srgb = Srgb::from_color(lch);
17
18        let r = (new_srgb.red * 255.0).round().clamp(0.0, 255.0) as u8;
19        let g = (new_srgb.green * 255.0).round().clamp(0.0, 255.0) as u8;
20        let b = (new_srgb.blue * 255.0).round().clamp(0.0, 255.0) as u8;
21
22        cloned_image.put_pixel(x, y, Rgba([r, g, b, pixel[3]]));
23    }
24
25    cloned_image
26}

Non-Destructive Undo/Redo State Stack

To support full non-destructive editing, HDIM encapsulates image transformations inside a History state manager. Image data is wrapped in atomic reference-counted smart pointers using DynamicImage to eliminate unnecessary deep copying during state pushes. When a user records a new adjustment after undoing, the stack automatically truncates future states before appending the new state.

1impl History {
2    pub fn record_state(&mut self, image: Arc<DynamicImage>, adjustments: Adjustments) {
3        // If we are not at the end of the history, truncate the future states
4        if self.current_index < self.states.len() - 1 {
5            self.states.truncate(self.current_index + 1);
6        }
7        self.states.push(HistoryState {
8            data: image,
9            adjustments,
10        });
11        self.current_index = self.states.len() - 1;
12    }
13
14    pub fn undo(&mut self) -> Option<HistoryState> {
15        if self.current_index > 0 {
16            self.current_index -= 1;
17            Some(self.states[self.current_index].clone())
18        } else {
19            None
20        }
21    }
22
23    pub fn redo(&mut self) -> Option<HistoryState> {
24        if self.current_index < self.states.len() - 1 {
25            self.current_index += 1;
26            Some(self.states[self.current_index].clone())
27        } else {
28            None
29        }
30    }
31}

Modular Crate Architecture

By decoupling core image mathematics (hdim-core), rendering math (hdim-render), and terminal UI layout (hdim-tui), HDIM achieves clear separation of concerns across a multi-crate workspace. The design ensures high terminal responsiveness while giving users granular control over metadata, image spatial transformations, and non-destructive image adjustments directly from their terminal.

Try It Out

Download

If you want to try this app out for yourself, click on the download button and install hdim.rar from GitHub, extract the .rar file and run the hdim executable. Alternatively you can use "cargo install hdim".

Video Demonstration

External Media Required

This video requires third-party cookies from YouTube to be displayed. Accepting will enable all external media across the site.