Pixel-Matrix-Language (PXLM)

Pixel-Matrix-Language (PXLM) is a human-readable image file format designed for storing pixel color data as a matrix of hexadecimal color codes. It is particularly useful for developers and AI tools, helping with debugging, visualization, and error correction. This format ensures data integrity, even in cases of image corruption, making it a reliable choice for various image processing tasks.

Features

• Human-readable format: Stores pixel color data as hexadecimal values in a matrix.
• Error correction: Handles corrupted or incomplete image data, replacing missing pixels with a default color (e.g., black).
• Versatility: Can be used in image processing, debugging, and visualization for AI tools and development.
• Easy conversion: Allows for seamless conversion between PXLM files and standard image formats (PNG, JPEG, etc.).

Installation

You can get started with PXLM by cloning the repository, using GitHub Desktop, or downloading the ZIP file. Here are the steps for each method:

Using Git (Command Line)

1. Open your terminal or command prompt.
2. Run the following command to clone the repository:

   git clone https://github.com/your-username/Pixel-Matrix-Language.git

Using GitHub Desktop

1. Open GitHub Desktop.
2. Go to File > Clone repository.
3. Select URL and paste the following:

   https://github.com/your-username/Pixel-Matrix-Language.git
   

4. Choose your destination folder and click Clone.

Downloading as a ZIP File

1. Go to the repository's page on GitHub.
2. Click the green Code button and select Download ZIP.
3. Extract the ZIP file to your preferred location on your computer.

Once the repository is downloaded or cloned, navigate to the project directory in your terminal.

Installing Requirements

To run the pxlm.py script, you'll need to install the required Python dependencies. Use the following command to install them:

pip install -r requirements.txt

How it Works

The .pxlm file format represents an image using a matrix of hexadecimal color codes. Each pixel in the image is represented by a 6-character hexadecimal string (e.g., #RRGGBB), where RR, GG, and BB are the red, green, and blue color values in hexadecimal format.

The PXLM format works as follows:

1. Hexadecimal Color Codes: Each pixel's color is represented by a 6-digit hexadecimal value (e.g., 4F0CFF, 9D2C30, etc.). This makes it easy to read and manipulate color data in a human-readable format.

2. Width & Line Structure: The pixel data is stored in rows, with each row containing a fixed number of pixels. The width of each row is defined in the .pxlm file, allowing for consistent alignment of pixels across multiple rows. This structure ensures that images are stored as a grid of color data, which can be easily converted back into an image.

3. Error Correction: If any pixel data is corrupted or missing, the PXLM format uses a default color (e.g., black) to fill in the gaps, ensuring the integrity of the data.

4. Human-Readable: PXLM files are plain text, which means they can be viewed and edited easily using any text editor. This is particularly useful for debugging, error checking, and manual adjustments to image data.

Here's an example of what a PXLM file might look like:

4F0CFF 9D2C30 1F7F38 2F5E7A 4BFA9D 0C5F1A 23F586 F5E206 D8D4A7 93D3B2
2D82F5 6DFF51 0E6E7A 7F3499 3A67E0 09C0B9 463F5F B7E552 12D06B 3BB0A0
4E95B9 6F4418 8D53DA D15E5E 1D1B6F 89A70A B95F24 4592C9 F462A1 8E9C16
C7D987 8A406F 26C0A4 0FBD15 8B5D8D 1B35AC 1C9D75 7B1B5C 2557D1 92F264
6F4937 F92BB4 9AE5FC C0C92C 6A2FBB A3D428 3C1D0F F9F68A 93D9D2 578AC3

File Structure

│   commands.sh
│   example.pxlm
│   LICENSE
│   pxlm.py
│   README.md
│   requirements.txt
│   
├───Image_to_pxlm
│       input.png
│       output.pxlm
│
├───Pxlm_to_image
│       input.pxlm
│       output.png
│
└───Validate_pxlm
        image.pxlm
        image_corrected.pxlm

Usage

Command-Line Operations

The script pxlm.py allows you to perform the following operations via the command line:

1. Validate and Correct a PXLM File

   • Validate the structure of a .pxlm file and correct any inconsistencies in pixel rows or missing pixels.

   python pxlm.py validate <path_to_pxlm_file>

   Example:

   python pxlm.py validate "path/to/Validate_pxlm/image.pxlm"

2. Convert an Image to PXLM Format

   • Convert an image (PNG, JPEG, WebP, etc.) to .pxlm format, storing pixel colors as hexadecimal values.

   python pxlm.py image_to_pxlm <path_to_image> <path_to_output_pxlm>

   Example:

   python pxlm.py image_to_pxlm "path/to/Image_to_pxlm/input.png" "path/to/Image_to_pxlm/output.pxlm"

3. Convert PXLM to Image

   • Convert a .pxlm file back to an image format (e.g., PNG).

   python pxlm.py pxlm_to_image <path_to_pxlm_file> <path_to_output_image>

   Example:

   python pxlm.py pxlm_to_image "path/to/Pxlm_to_image/input.pxlm" "path/to/Pxlm_to_image/output.png"

Example PXLM File

Here is an example of a .pxlm file (example.pxlm), which contains color data for an image in hexadecimal format:

4F0CFF 9D2C30 1F7F38 2F5E7A 4BFA9D 0C5F1A 23F586 F5E206 D8D4A7 93D3B2
2D82F5 6DFF51 0E6E7A 7F3499 3A67E0 09C0B9 463F5F B7E552 12D06B 3BB0A0
4E95B9 6F4418 8D53DA D15E5E 1D1B6F 89A70A B95F24 4592C9 F462A1 8E9C16
C7D987 8A406F 26C0A4 0FBD15 8B5D8D 1B35AC 1C9D75 7B1B5C 2557D1 92F264
6F4937 F92BB4 9AE5FC C0C92C 6A2FBB A3D428 3C1D0F F9F68A 93D9D2 578AC3
D302A2 28C8F0 3BBF8A 1B0C3E 76E00A F7D4D0 95A07E 82A523 097120 69F3F1
DC8E10 36D88B 87F6A5 5F67F7 8EAD8A C8AC56 23F4D2 60B8FF 4A6015 9FDC5E
CF03A4 29F815 1106A2 7A5299 83A87E 04A2DC 4E5403 2E5D52 53F0F6 7B4921
6E2A14 B473E5 9C0F71 A182E6 6A70E7 00A8C5 2B6485 98D9B6 A9D23F 64D9BC
4A

5050 88A1E6 22FB19 399AF6

Contributing

We welcome contributions! To contribute to the project, follow these steps:

1. Fork the repository.
2. Clone your fork to your local machine.
3. Make your changes and test them.
4. Submit a pull request with a detailed explanation of the changes.

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.