PX2PS

A PowerShell module that converts Pixquare .px files to terminal pixel graphics using ANSI True Color in terminals that support ANSI escape sequences and ConsoleColor in terminals that don't. (Please don't use ISE anymore...)

Installation

From the PowerShell Gallery (preferred):

Install-Module -Name PX2PS -Scope CurrentUser -Force

From source:

# Clone the repository
git clone https://github.com/jakehildreth/PX2PS.git

# Import the module
Import-Module ./PX2PS/PX2PS.psd1

Quick Start

# Convert and display a .px file
Convert-PX2PS -Path "image.px"

# Convert all .px files in a directory using alias
px2ps -Path "C:\PixelArt"

# Pipeline support
Get-ChildItem -Path . -Filter "*.px" | Convert-PX2PS

# Get scriptblock for deferred rendering
$sb = Convert-PX2PS -Path "logo.px" -OutputMode ScriptBlock
& $sb

# Generate standalone script file
Convert-PX2PS -Path "banner.px" -OutputMode Script -OutputPath "banner.ps1"

# -PassThru to get pixel data without rendering
$imageData = px2ps -Path "image.px" -PassThru
Write-Host "Dimensions: $($imageData.Width)x$($imageData.Height)"

Features

• Renders .px files directly in the terminal using ANSI True Color
• Supports single-layer and multi-layer .px files
• Automatic layer compositing and transparency handling
• ScriptBlock output for deferred rendering
• Standalone script generation
• Cross-platform support (Windows, Linux, macOS)
• PowerShell 5.1+ compatible
• Pipeline input support

Requirements

• PowerShell 5.1 or later

How It Works

PX2PS reads Pixquare .px files, decompresses the zlib-encoded layer data, composites multiple layers if present, and renders the final image using Unicode lower half block characters (▄) with ANSI True Color escape sequences. Each terminal line represents two rows of pixels.

In terminals that do not support ANSI sequences (e.g., PowerShell ISE), pixels are written using ConsoleColor instead of ANSI.

Local Build

Use PowerShell 7.4 or later for builds and tests:

Install-Module PSPublishModule -RequiredVersion 2.0.27 -Scope CurrentUser -AllowClobber
Install-Module Pester -RequiredVersion 6.1.0 -Scope CurrentUser -AllowClobber

Import-Module Pester -RequiredVersion 6.1.0
Invoke-Pester -Path ./Tests -CI

# Build only. Nothing is published.
pwsh -NoProfile -File ./Build/Build-Module.ps1

# Build a specific prerelease version.
pwsh -NoProfile -File ./Build/Build-Module.ps1 -CalVer 2026.10.41234 -Prerelease pre

The package is written to Artefacts/Unpacked/PX2PS. Each build uses an isolated working directory. It does not replace an installed copy of PX2PS.

To publish locally, set PSGALLERY_API_KEY, GITHUB_TOKEN, and GITHUB_SHA in your environment, then run:

pwsh -NoProfile -File ./Build/Build-Module.ps1 -PublishToPSGallery -PublishToGitHub

Use a new CalVer for each publication. Rerunning a release with an existing version fails rather than replacing it.

License

MIT License w/Commons Clause - see LICENSE file for details.

---

Made with 💜 by Jake Hildreth