HexPaint

HexPaint is a GUI-based utility designed to map hexadecimal color codes from an Excel spreadsheet and visually apply them as solid cell background fills in newly generated columns. The application ensures your data layout matches structural requirements through a built-in guide, parses multiple sequentially labeled 'Hex X' columns, and outputs color-mapped results while keeping your original formatting intact #️⃣➡️🎨

➡️ Read more about the project, its features, and development in my Medium story or visit the Interactive Project Card.

Table of Contents

• Overview
• Key Features
• Installation
• Usage
• Project Structure
• Development
• Known Issues
• Contributing
• License
• Contact

Overview

HexPaint simplifies the process of visually validating and displaying color codes stored in Excel sheets. Instead of manually copying hex codes and coloring cells, this utility automatically processes your spreadsheet, identifies color source columns, and creates styled "Visual" columns filled with the exact hex colors.

The core strength of HexPaint is its structured parsing and robust validation logic. It checks for headers specifically on Row 2 (allowing Row 1 to be used for titles), ignores empty leading columns to preserve layout alignment, and flags formatting errors with a distinctive light-red error fill.

Problem it Solves

• Visualizing Color Palettes at Scale: Allows designers, developers, and analysts to easily view dozens, hundreds, or thousands of hex colors directly within Excel simply by providing their codes. This dramatically simplifies the task of identifying, coordinating, and matching color schemes.
• Manual Formatting Fatigue: Eliminates the tedious task of manually coloring individual cells based on hex values.
• Validation Errors: Instantly identifies invalid hex formats (missing characters, wrong symbols) by flagging them with a distinct background fill.
• Dynamic Layout Alignment: Safely skips empty or unnamed columns that often skew standard data parsers, ensuring column relationships remain correct.

Typical Workflow

1. Launch the application and review the "Excel Layout Requirements" dialog.
2. Select your input Excel file (.xlsx or .xls) through the native file dialog.
3. Confirm the suggested, timestamped output path and filename.
4. Watch as the utility scans the Row 2 headers, creates missing 'Visual Hex' columns, parses colors, and formats cells.
5. Review the completion popup, with an option to instantly open the file's location in macOS Finder.

Key Features

• Educational Layout Helper: Displays an instructional window detailing structural rules before processing, helping users format their source sheets correctly.
• Dynamic Column Creation: Automatically creates corresponding Visual Hex X output columns if they do not already exist, or updates existing ones in place.
• Smart Column Detection: Bypasses leading unnamed/empty columns and sorts sequentially labeled Hex X columns numerically.
• Robust Hex Parsing & Validation: Validates formats (6 or 8 characters) and processes strings, floats, and integers.
• Visual Error Indicators: Flags invalid formats or missing values with a distinctive light-red error fill (FFC7CE) for rapid diagnostic review.
• Automatic Column Widths: Adjusts column dimensions for new "Visual" target columns to prevent clipped text or squished cells.
• Quick File Reveal: Provides a modal complete screen with a button to instantly open the output folder and highlight the saved file (optimized for macOS).

Installation

Prerequisites

• Python 3.6+
• A graphical desktop environment is required to run the tkinter-based GUI.

Clone the Repository

git clone https://github.com/sztaroszta/HexPaint.git
cd HexPaint

Install Dependencies

You can install the required dependencies using pip:

pip install -r requirements.txt

Alternatively, install the dependencies manually:

pip install pandas openpyxl

Usage

1. Prepare your Excel File: Ensure your .xlsx file has column headers on Row 2 (Row 1 can be empty or used for notes). The source columns must follow the naming pattern Hex 1, Hex 2, etc.

Column B (ID)	Column C (Name)	Column D (Hex 1)	Column E (Visual Hex 1)
101	Project Alpha	#FF0000	[Auto-Filled Color]
102	Project Beta	00FF00	[Auto-Filled Color]

2. Run the application:

python excel_hex_mapper.py

3. Follow the GUI Prompts:

• Layout Requirements: Review the configuration guidelines and click "I Understand, Select File" to proceed.

  

• Select Input File: Choose your source Excel file containing the hex codes. You can use the example.xlsx file from the dataset folder to test the tool.

  

• Save File As: Confirm the save path and the suggested filename, which automatically prepends a timestamp (e.g., input_file_hexmapped_YYYYMMDD_HHMMSS.xlsx).

• Review Results: A success modal displays when the task is complete. Click "Open File Location" to view the generated spreadsheet.

  

• Verify Colored Outputs: Open the generated workbook (such as example_hexmapped.xlsx) to inspect the newly created Visual Hex X columns formatted with solid color fills.

  

Project Structure

HexPaint/
├── assets/                 # Contains screenshots of the application's UI
├── dataset/                # Example input and output Excel files for testing
├── excel_hex_mapper.py     # Main Python script containing the GUI and processing logic
├── .gitignore              # Git ignore file for Python projects
├── LICENSE                 # MIT License File
├── README.md               # Project documentation
└── requirements.txt        # List of dependencies

• excel_hex_mapper.py: Contains the complete program with all GUI components, layout validation, hex processing logic, and Excel styling functionality.
• dataset/: Includes sample spreadsheets with input colors and processed visual outputs to test and verify functionality.
• assets/: Contains screenshots that illustrate the application's user interface and functionality.
• LICENSE: Defines the usage rights under the MIT License.

Development

Guidelines for contributors:

If you wish to contribute or enhance HexPaint:

• Coding Guidelines: Follow Python best practices (PEP 8). Use meaningful variable names and add clear comments or docstrings.
• Testing: Before submitting changes, please test them locally with various Excel files to ensure existing functionality is not broken.
• Issues/Pull Requests: Please open an issue or submit a pull request on GitHub for enhancements or bug fixes.

Known Issues

• Platform Specificity: The "Open File Location" action in the completion window uses the macOS-native command open -R to reveal the file in Finder. Running the script on Windows or Linux may cause an error when clicking this button, though the main file generation remains unaffected.
• Layout Rigidity: The script expects headers on Row 2 (0-indexed index 1 in pandas). Files with headers starting on Row 1 or Row 3 may fail to map correctly.
• Style Extraction Limitations: When parsing existing visual columns, the utility attempts to parse color codes from cell value strings (e.g., #FFFFFF), rather than extracting the direct cell fill style itself.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or fix.
3. Commit your changes with descriptive messages.
4. Push to your fork and submit a pull request.

For major changes, please open an issue first to discuss the proposed changes.

License

Distributed under the MIT License. See LICENSE for full details.

Contact

For questions, feedback, or support, please open an issue on the GitHub repository or contact me directly:

Visualize your palette, master your design! 🎨📊

Version: 4

Concept Date: 2025-05-23