Module density 

Character density-based rendering

This module provides intensity-to-character mapping for creating ASCII-art style visualizations. It enables rendering of smooth gradients and shading effects by mapping floating-point intensity values [0.0, 1.0] to characters of varying visual density.

Key Concepts

Intensity Mapping: Convert grayscale intensity values (0.0 = black, 1.0 = white) to characters that represent different visual densities:

• Low intensity (dark): sparse characters like space ’ ’, dot ‘.’
• High intensity (bright): dense characters like hash ‘#’, at-sign ‘@’

Density Sets: Collections of characters ordered from sparse to dense. The module provides predefined sets optimized for different use cases:

• ASCII_DENSITY: Full 69-character gradient for maximum smoothness
• SIMPLE_DENSITY: Simple 10-character gradient for quick prototypes
• BLOCKS_DENSITY: Unicode block characters for modern terminals
• BRAILLE_DENSITY: Braille dot progression (unique to dotmax)

Examples

Using Predefined Density Sets

use dotmax::density::DensitySet;

// Create predefined density set
let density = DensitySet::ascii();

// Map intensity values to characters
assert_eq!(density.map(0.0), ' ');  // Darkest (first character)
assert_eq!(density.map(1.0), '$');  // Brightest (last character)
// Middle intensity maps to a character ~34th in the 69-char sequence
let mid_char = density.map(0.5);
assert!(mid_char != ' ' && mid_char != '$');  // Somewhere in the middle

Creating Custom Density Sets

use dotmax::density::DensitySet;

// Create custom density set
let custom = DensitySet::new(
    "Custom".to_string(),
    vec![' ', '.', 'o', 'O', '@']
).unwrap();

// Map intensities using custom set
assert_eq!(custom.map(0.0), ' ');   // Sparse
assert_eq!(custom.map(0.25), '.');  // Low density
assert_eq!(custom.map(0.5), 'o');   // Medium density
assert_eq!(custom.map(0.75), 'O');  // High density
assert_eq!(custom.map(1.0), '@');   // Dense

Rendering Intensity Buffers

use dotmax::{BrailleGrid, density::DensitySet};

// Create grid and generate intensity buffer
let mut grid = BrailleGrid::new(10, 5).unwrap();
let intensities: Vec<f32> = (0..50)
    .map(|i| i as f32 / 49.0)  // Gradient from 0.0 to 1.0
    .collect();

// Render using density set
let density = DensitySet::simple();
grid.render_density(&intensities, &density).unwrap();

Performance

• Intensity mapping: O(1) per cell (array index lookup)
• Grid rendering: O(n) where n = width × height cells
• Expected: ~1μs per cell = ~2ms for 80×24 terminal
• Target: <10ms for full terminal rendering (validated with benchmarks)

Predefined Density Sets

Constant	Characters	Use Case
ASCII_DENSITY	69 chars	Maximum gradient smoothness
SIMPLE_DENSITY	10 chars	Quick prototypes, minimal variation
BLOCKS_DENSITY	5 chars	Block-based shading (Unicode)
BRAILLE_DENSITY	9 chars	Braille-themed density progression

Structs

DensitySet

Character density set for intensity-based rendering

Constants

ASCII_DENSITY

Predefined ASCII density character set (69 characters)

BLOCKS_DENSITY

Predefined Unicode block density character set (5 characters)

BRAILLE_DENSITY

Predefined braille density character set (9 characters)

SIMPLE_DENSITY

Predefined simple density character set (10 characters)