ImageAI-Upscale

ImageAI-Upscale is a custom PyTorch model for sparse pixel completion and 2x-by-2x canvas-based image upscaling.

The idea behind this model is simple:

1. Take an input image.
2. Expand the canvas to 2x width and 2x height.
3. Place each original pixel into the bottom-left position of a 2x2 block.
4. Leave the other 3 pixels empty (black).
5. Let the model fill the missing pixels.

This produces an output image with:

• 2x width
• 2x height
• 4x total pixel count

What Is Included

This repository contains:

• best.pt: trained model checkpoint
• sparse_unet_native_bc96.yaml: model/training config
• example_input.png: sample input image
• example_output.png: sample output image

Model Type

This is a custom full-image sparse completion model, not a standard Transformers or Diffusers model.

Architecture summary:

• custom PyTorch U-Net
• pixel-unshuffle based sparse representation
• trained to reconstruct dense RGB output from sparse structured input
• final inference runs on the full image directly, without tiling

Training Summary

The model was trained on a PNG image dataset prepared from a larger original image collection.

Training pipeline summary:

• all source images were converted to PNG
• full-resolution images were used as the master dataset
• to make training more efficient, each full-resolution image was split into 16 parts
• sparse training pairs were created from those image tiles
• each 2x2 sparse block kept only the bottom-left pixel
• the other 3 pixels were set to black

The model was then trained to learn:

• SparsePNG -> MasterPNG

This means the model specifically learns how to restore this exact sparse pattern.

Important Limitation

This model is not a general-purpose super-resolution model.

It works best when the input follows the same sparse structure used during training:

• each original pixel is placed into the bottom-left position of a 2x2 block
• the other three pixels in that block are black

If you feed normal images directly, you should first convert them into this sparse canvas format.

Intended Use

This model is intended for:

• experimental image upscaling workflows
• sparse pixel reconstruction research
• custom image-to-image pipelines where the sparse sampling rule is fixed

Example Usage

This repository stores only the model assets. The runtime is expected to be used with the original local project code.

Example command:

python -m imageai.upscale_cli ^
  --input "D:\AI\ImageAI\Test.png" ^
  --output "D:\AI\ImageAI\Test_upscaled.png" ^
  --config "D:\AI\ImageAI\configs\sparse_unet_native_bc96.yaml" ^
  --ckpt "D:\AI\ImageAI\checkpoints\sparse_unet_native_bc96\best.pt"

Or, if the CLI entrypoint is installed:

imageai-upscale --input "input.png" --output "output.png"

Notes

• trained with PyTorch
• designed around full-image inference
• developed as a custom research/project pipeline rather than a framework-native Hugging Face architecture

License

MIT