VisualizeAlignment

Basic Usage

visualizealignment.sh <map>
visualizealignment.sh <map> <image>

This tool converts text-based alignment visualization maps generated by various aligners into visual bitmap images. The tool automatically detects the output format based on the file extension.

Parameters

VisualizealignmentParameters are minimal as this is a specialized conversion utility focused on transforming aligner output into visual representations.

Parameters

map: Text file of score-space from an aligner. This file contains character-based representations of alignment scores generated by aligners like Quantum, Banded, Drifting, Glocal, WaveFront, and MSA9. Required parameter.
image: Output name, context sensitive; supports png, bmp, jpg. Image name is optional; if absent, .txt will be replaced by .png in the input filename. The tool automatically determines the output format from the file extension.

Examples

Basic Conversion

visualizealignment.sh alignment_map.txt

Converts alignment_map.txt to alignment_map.png using default PNG format.

Specify Output Format

visualizealignment.sh alignment_map.txt visualization.jpg

Converts the alignment map to JPEG format with custom filename.

Multiple Format Support

visualizealignment.sh quantum_output.txt quantum_vis.bmp

Creates a bitmap image from Quantum aligner output.

Algorithm Details

VisualizationConverter uses two distinct color mapping methods (getColorForChar1 and getColorForChar2) with linear interpolation to transform character-based alignment score representations into bitmap images.

Color Mapping System

The tool uses a dual color scheme system to represent different alignment score ranges:

Special Characters

Space (' '): Black - Represents unexplored regions in the alignment space
Period ('.'): Dark Gray (RGB: 80,80,80) - Explored but pruned regions
Asterisk ('*'): White - Optimal alignment path

Score Characters (Color Scheme 1 - Default)

Letters 'a'-'p' (16 steps): Green range from dark green (0,96,0) to bright green (0,255,0)
Letters 'q'-'z' (10 steps): Green to yellow transition (0,255,0) to (240,255,0)
Digits '0'-'9' (10 steps): Yellow to orange range (255,255,0) to (255,180,0)
Letters 'A'-'T' (20 steps): Orange to red range (255,170,0) to (255,16,0)
Letters 'U'-'Z' (6 steps): Red to purple range (255,0,16) to (96,32,255)

Score Characters (Color Scheme 2 - Alternative)

Letters 'a'-'p': Blue range from dark blue (0,0,128) to bright blue (0,100,255)
Letters 'q'-'z': Blue to cyan transition (0,100,255) to (0,210,210)
Digits '0'-'9': Cyan to yellow range (0,210,210) to (240,240,0)
Letters 'A'-'T': Yellow to purple range (240,240,0) to (170,0,255)
Letters 'U'-'Z': Purple to magenta range (170,0,255) to (255,0,170)

Automatic Scaling

The tool implements conditional scaling based on input width:

Default Scale Factor: 2x (each character becomes a 2x2 pixel block)
Large Image Optimization: For text files with width ≥2000 characters, scaling is reduced to 1x to prevent excessive memory usage
Streaming Processing: Uses BufferedReader to read input line-by-line, avoiding full file loading into memory

Format Support

The tool automatically detects and supports multiple output formats:

PNG: Default format, lossless compression ideal for visualization data
JPEG/JPG: Compressed format for smaller file sizes
BMP: Uncompressed bitmap format for maximum compatibility

Performance Characteristics

Memory Usage: Scales linearly with image dimensions (width × height × scale²)
Processing Speed: Single-pass algorithm with O(n) complexity where n is the number of characters
File Size Handling: No explicit size limits; constrained only by available memory
Color Interpolation: Uses interpolateColor() method with RGB component-wise linear interpolation between gradient endpoints

Supported Aligners

This tool is designed to work with visualization output from several alignment algorithms:

Quantum: Quantum alignment algorithm visualization
Banded: Banded dynamic programming alignment visualization
Drifting: Drifting alignment algorithm output
Glocal: Global-local alignment visualization
WaveFront: WaveFront alignment algorithm output
MSA9: Multiple sequence alignment visualization

Support

For questions and support:

Email: bbushnell@lbl.gov
Documentation: bbmap.org