Dot Matrix Tool

A web application for generating character or image byte arrays for dot matrix style OLED or LCD displays.

Features

Core Functionality

• Visual Dot Matrix Editor: Draw and erase pixels with mouse clicks
• Multiple Byte Order Support: Row major, column major, and column+row hybrid byte ordering
• Endianness Selection: Support for both big-endian and little-endian output
• Dynamic Size Adjustment: Support for any size from 1×1 to 128×128 pixels
• C Code Generation: Automatically generate ready-to-use C language byte array code

Text Features (Core Highlight)

• Dual Font System Support:
  • Built-in Bitmap Fonts: 7×6 and 12×8 pixel perfectly optimized fonts, designed specifically for dot matrix displays
  • System Font Rendering: Support for system font rendering (future feature)
• Intelligent Text Rendering Engine:
  • Multi-language Character Support: Complete English letters, numbers, and common symbols library
  • Character Spacing Optimization: Automatic character spacing adjustment for optimal display
  • Multi-line Text Processing: Support for line breaks with automatic multi-line text layout
• Advanced Typography Features:
  • Three Alignment Modes: Left, center, and right alignment
  • Precise Position Control: Pixel-level X/Y coordinate positioning
  • Smart Content Merging: Option to merge with existing content or completely replace
• Real-time Preview System:
  • Instant Preview: Real-time display of rendering effects during text input
  • Position Preview: Visual display of exact text position in grid
  • Merge Effect Preview: Preview of merging effects with existing content

Data Management

• Project Save/Load: Support for saving and loading project files in JSON format
• Code Import: Reverse import from existing C byte array code to editor
• Multi-format Export: Support for exporting JSON project files and C code files
• Real-time Preview: Real-time preview functionality during text input

Interface Features

• Bilingual Support: Complete Chinese and English interface switching
• Responsive Design: Adapts to different screen sizes
• Intuitive Operation: Left click to draw, right click (or Ctrl+Left) to erase
• Real-time Feedback: Display current grid size, byte order, and other information

Program Architecture

Frontend Technology Stack

• HTML5: Modern web standards with semantic tags
• CSS3: Responsive layout with Bootstrap 4 framework
• JavaScript (ES5): Core logic implementation with jQuery library support
• Web Fonts: Google Fonts (Roboto Mono)

Core Modules

1. Matrix Management Module (app.js)

// Core data structures
var matrix;           // 2D array storing pixel data
var rowMajor;         // Byte order control
var msbendian;        // Endianness control
var columnPlusRow;    // Column+row hybrid mode

2. Font Management Module (FontManager)

var FontManager = {
  fonts: {},                    // Font cache
  loadFont: function(),         // Font loading
  getCharacterData: function()  // Character data retrieval
};

3. Text Rendering Module (TextRenderer)

var TextRenderer = {
  renderCharacter: function(),  // Single character rendering
  renderText: function(),       // Text rendering
  generatePreview: function()   // Preview generation
};

4. Language Management Module (language.js)

var LANGUAGE = {
  'en': { /* English translations */ },
  'zh': { /* Chinese translations */ }
};

5. Font Data Module (embedded-fonts.js)

const FONT_DATA = {
  "7x6": { /* 7×6 pixel font data */ },
  "12x8": { /* 12×8 pixel font data */ }
};

Data Flow

1. User Input → Mouse event handling → Matrix data update
2. Matrix Data → Byte array generation → C code output
3. Text Input → Font rendering → Matrix merging → Display update
4. Project Save → JSON serialization → File download
5. Project Load → File reading → JSON parsing → Matrix reconstruction

Usage Guide

Basic Operations

1. Drawing Pixels

   • Left click: Draw pixel
   • Right click or Ctrl+Left click: Erase pixel
   • Drag: Continuous drawing or erasing

2. Size Adjustment

   • Modify width/height input boxes (1-128 pixels)
   • Real-time grid size adjustment

3. Code Generation

   • Click "Generate" button
   • View C language byte array in output area

Advanced Features

Text Input (Core System Feature)

The text input functionality is a major highlight of this tool, providing professional-grade text rendering capabilities:

Basic Operation Flow:

1. Click "Text Input" button to open the text editor
2. Enter content to render in the text area (supports multi-line text)
3. Select font specification:
   • 7×6 Pixel Font: Compact font, suitable for small displays
   • 12×8 Pixel Font: Standard font, suitable for medium-sized displays
4. Configure typography parameters:
   • Alignment: Left/Center/Right alignment
   • X Position: Horizontal offset (pixel-level precision)
   • Y Position: Vertical offset (pixel-level precision)
5. Choose rendering mode:
   • Merge Mode: Overlay with existing content
   • Replace Mode: Clear existing content before rendering
6. Real-time Preview: View final effects in preview area
7. Confirm and click "Apply"

Advanced Features:

• Character Integrity Check: Automatically detect unsupported characters and provide alternatives
• Intelligent Boundary Handling: Automatically handle text exceeding grid boundaries
• Multi-line Text Support: Use line breaks to create multi-line display effects
• Position Guidance: Visual display of text area boundaries
• Undo Support: Use "Clear" function to undo text rendering

Font Technical Details:

• All fonts are hand-optimized bitmap fonts
• Each character is optimized for dot matrix displays
• Supports complete ASCII character set (32-126)
• Character spacing carefully adjusted for optimal readability

Byte Order Configuration

• Row Major: Row scanning, suitable for row-scan displays
• Column Major: Column scanning, suitable for column-scan displays
• Column+Row: 8-pixel grouped column scanning, commonly used for OLED displays

Endianness

• Big Endian: High byte first, suitable for most embedded systems
• Little Endian: Low byte first, suitable for x86 architecture

Project Management

Save Project

1. Click "Save" button
2. Automatically download JSON format project file
3. Filename includes timestamp: dot_matrix_YYYY-MM-DD_HH-MM-SS.json

Load Project

1. Click "Load" button
2. Select previously saved JSON file
3. Automatically restore all settings and pixel data

Import Code

1. Paste existing C byte array code in output area
2. Click "Import" button
3. Automatically parse and display in grid

Export Functions

Export JSON

• Click "Export JSON" button
• Download JSON file containing complete project data

Export Code

• Click "Export Code" button
• Download .c file containing C language byte array

Technical Details

Byte Array Generation Algorithm

Column+Row Mode (Recommended for OLED)

// Column scanning in groups of 8 pixels
for (var yBlock = 0; yBlock < paddedHeight; yBlock += 8) {
  for (var x = 0; x < width; x++) {
    var newByte = 0;
    for (var bit = 0; bit < 8; bit++) {
      var y = yBlock + bit;
      var bitVal = (y < height && matrix[y][x]) ? 1 : 0;
      newByte |= bitVal << (msbendian ? (7 - bit) : bit);
    }
    bytes.push(newByte);
  }
}

Row Major Mode

// Row-by-row pixel scanning
for (var y = 0; y < height; y++) {
  for (var x = 0; x < width; x++) {
    buffer[y * width + x] = matrix[y][x];
  }
}

Font Rendering System

Each character is defined as a 2D array:

"A": [
  [0,1,1,1,0,0],
  [1,0,0,0,1,0],
  [1,0,0,0,1,0],
  [1,1,1,1,1,0],
  [1,0,0,0,1,0],
  [1,0,0,0,1,0],
  [1,0,0,0,1,0]
]

Browser Compatibility

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

Development Environment

Project Structure

├── index.html          # Main page
├── app.js             # Core logic
├── embedded-fonts.js  # Font data
├── language.js        # Multi-language support
├── cover.css          # Style file
├── readme_cn.md       # Chinese documentation
├── readme_en.md       # English documentation
└── .gitignore         # Git ignore file

Local Development

1. Clone the project locally
2. Open with a web server (such as Live Server)
3. Or directly open index.html in browser

Custom Development

Adding New Fonts

1. Define character data in embedded-fonts.js
2. Register new font in FontManager.loadFont()
3. Add option in text input dialog

Adding New Languages

1. Add translations in LANGUAGE object in language.js
2. Add new option in language switch buttons
3. Update updateUILanguage() function

Use Cases

Embedded Display Development

• Arduino + OLED display projects
• STM32 + LCD display applications
• Raspberry Pi display projects
• Microcontroller character displays

Icon and Character Design

• Custom font creation
• Pixel art design
• Icon prototyping
• Dot matrix animation frame design

Education and Learning

• Digital image processing teaching
• Embedded systems courses
• Computer graphics experiments
• Programming education tools

Performance Optimization

Memory Management

• Efficient 2D array operations
• Optimized font data caching
• Minimal DOM manipulation

Rendering Optimization

• CSS-based grid rendering
• Hardware-accelerated transforms
• Responsive cell sizing

Code Generation Efficiency

• Optimized byte packing algorithms
• Efficient bit manipulation
• Minimal memory allocation

Advanced Configuration

Custom Byte Orders

The tool supports three main byte ordering modes:

1. Row Major: Sequential row scanning

   • Best for: Traditional LCD controllers
   • Memory layout: [row0][row1][row2]...

2. Column Major: Sequential column scanning

   • Best for: Vertical scanning displays
   • Memory layout: [col0][col1][col2]...

3. Column+Row Hybrid: 8-pixel vertical blocks

   • Best for: SSD1306 OLED controllers
   • Memory layout: [8-pixel vertical blocks]

Font System Architecture

The embedded font system uses a hierarchical structure:

FONT_DATA = {
  "fontName": {
    "name": "Display Name",
    "width": pixelWidth,
    "height": pixelHeight,
    "characters": {
      "char": [[pixel_matrix]]
    }
  }
}

Export Formats

• C Array: Standard embedded C format
• JSON Project: Complete project state
• Binary Data: Raw byte sequences (future feature)

Troubleshooting

Common Issues

1. Grid not displaying: Check browser JavaScript support
2. Font not loading: Verify embedded-fonts.js is loaded
3. Export not working: Check browser download permissions
4. Import failing: Verify C array format syntax

Performance Tips

• Use smaller grid sizes for better performance
• Clear unused pixels to reduce memory usage
• Use appropriate byte order for your target hardware

API Reference

Core Functions

// Matrix operations
createArray(height, width)
updateTable()
generateByteArray()

// Font operations
FontManager.loadFont(fontName, callback)
TextRenderer.renderText(fontName, text, alignment)

// File operations
saveMatrix()
loadMatrix(event)
exportCode()

Acknowledgments

This project is based on the open-source project dotmatrixtool by Stefan Gordon. We thank the original author for providing an excellent foundation framework. Building upon this base, we have added the following significant features:

• Complete Chinese and English bilingual support
• Advanced text input and rendering system
• Built-in font library (7×6 and 12×8 pixel fonts)
• Project file save/load functionality
• Code import/export functionality
• Real-time preview system
• Responsive interface design
• Enhanced user experience

The original project provided the core matrix editing functionality and basic code generation. Our enhancements focus on usability, internationalization, and advanced text handling capabilities, making it a more comprehensive tool for embedded display development.

Author & Contact

Author: Taber.Huang
Email: [email protected]
Version: v0.1.0
Release Date: Sept 11, 2025

License

This project is open-sourced under the MIT License. See the LICENSE file for details.

Contributing

Issues and Pull Requests are welcome to improve this project.

Roadmap

Planned Features

• Additional font sizes (5×7, 8×8, 16×16)
• Image import functionality
• Animation frame support
• Custom color themes
• Keyboard shortcuts
• Undo/Redo functionality
• Grid guidelines and rulers
• Batch export capabilities

Future Enhancements

• WebAssembly optimization for large grids
• Progressive Web App (PWA) support
• Cloud storage integration
• Collaborative editing features
• Plugin system for custom exporters
• Mobile app versions