Image2Text.psm1

<#
.SYNOPSIS
Converts images to ASCII art with optional color rendering and file export.
 
.DESCRIPTION
This module provides a high-performance wrapper around a .NET-based image-to-text converter. It transforms raster images into terminal-friendly ASCII representations, with support for:
 
- True-color ANSI output for rich console rendering
- Aspect ratio correction and gamma tuning
- File export with automatic plain-text formatting
- Parameter sets to enforce safe and predictable usage
 
Designed for PowerShell 6 and 7+, it supports creative automation, terminal art, and comic-style branding workflows.
 
.PARAMETER ImagePath
Path to the input image file (e.g., PNG, JPG, BMP).
 
.PARAMETER Width
Target width in characters for the ASCII output. Height is auto-calculated based on image dimensions and aspect ratio.
 
.PARAMETER AspectRatio
Aspect ratio correction factor to compensate for character height distortion in terminal fonts. Default is 0.55.
 
.PARAMETER Gamma
Gamma correction factor to adjust perceived brightness. Default is 2.2.
 
.PARAMETER UseColor
Switch to enable true-color ANSI output for console rendering. Only available in the 'Console' parameter set.
 
.PARAMETER SaveToFile
Path to save the ASCII output as a plain-text file. Automatically strips ANSI codes. Only available in the 'File' parameter set.
 
.PARAMETER InvertColor
Switch to invert image colors before conversion. Only available in the 'File' parameter set. This uses MS Paint to perform the inversion.
 
.EXAMPLE
Convert-Image2Text -ImagePath "C:\Images\logo.png" -Width 150 -UseColor
 
.EXAMPLE
Convert-Image2Text -ImagePath "C:\Images\logo.png" -Width 150 -SaveToFile "C:\Output\logo.txt"
 
.EXAMPLE
Convert-Image2Text -ImagePath "C:\Images\logo.png" -Width 400 -SaveToFile "C:\Output\logo.txt" -InvertColor
 
.NOTES
Author: Adam B.
Module: Image2Text
Version: 1.0.0
License: MIT
#>


# Load the compiled .NET assembly vital to this module's functionality
$assemblyPath = Join-Path $PSScriptRoot 'Image2Text.dll'
if (-not (Test-Path $assemblyPath)) {
    throw "Required assembly not found: $assemblyPath"
}
Add-Type -Path $assemblyPath

function Convert-Image2Text {
    [CmdletBinding(DefaultParameterSetName = 'Console')]
    param (
        [Parameter(Mandatory, ParameterSetName = 'Console')]
        [Parameter(Mandatory, ParameterSetName = 'File')]
        [string]$ImagePath,

        [Parameter(ParameterSetName = 'Console')]
        [Parameter(ParameterSetName = 'File')]
        [int]$Width = 100,

        [Parameter(ParameterSetName = 'Console')]
        [Parameter(ParameterSetName = 'File')]
        [double]$AspectRatio = 0.55,

        [Parameter(ParameterSetName = 'Console')]
        [Parameter(ParameterSetName = 'File')]
        [double]$Gamma = 2.2,

        [Parameter(ParameterSetName = 'Console')]
        [switch]$UseColor,

        [Parameter(Mandatory, ParameterSetName = 'File')]
        [string]$SaveToFile,

        [Parameter(ParameterSetName = 'File')]
        [switch]$InvertColor

    )

    try {
        if (-not (Test-Path $ImagePath)) {
            throw "Image file not found: '$ImagePath'"
        }

        $useColorFlag = $UseColor.IsPresent
        $lines = [Image2Text.AsciiConverter]::Convert($ImagePath, $Width, $AspectRatio, $Gamma, $useColorFlag)

        if ($PSCmdlet.ParameterSetName -eq 'File') {
            if ($PSCmdlet.ParameterSetName -eq 'File') {
                # Always strip ANSI codes for file output
                $lines = $lines | ForEach-Object { $_ -replace "\u001b\[[0-9;]*m", "" }
            }

            $parentFolder = Split-Path $SaveToFile -Parent
            if (-not (Test-Path $parentFolder)) {
                throw "SaveToFile path is invalid or the folder does not exist: '$parentFolder'"
            }

            if ($InvertColor.IsPresent) {
                $tempPath = Join-Path $env:TEMP ("inverted_" + [System.IO.Path]::GetFileName($ImagePath))
                Copy-Item $ImagePath $tempPath -Force
                Write-Host "Inverting image colors via MS Paint..."

                # Launch Paint
                Start-Process "mspaint.exe" -ArgumentList "`"$tempPath`""
                Start-Sleep -Seconds 2  # Give Paint time to open

                # Create VBScript to send keys
                $vbs = @"
Set WshShell = WScript.CreateObject("WScript.Shell")
WScript.Sleep 1000
WshShell.SendKeys "^a"
WScript.Sleep 500
WshShell.SendKeys "^+i"
WScript.Sleep 500
WshShell.SendKeys "^s"
WScript.Sleep 500
WshShell.SendKeys "%{F4}"
"@


                $vbsPath = Join-Path $env:TEMP "invertPaint.vbs"
                Set-Content -Path $vbsPath -Value $vbs -Encoding ASCII

                # Run the VBScript
                Start-Process "wscript.exe" -ArgumentList "`"$vbsPath`"" -WindowStyle Hidden

                Start-Sleep -Seconds 3  # Wait for Paint to close and save

                # Use the inverted image
                $ImagePath = $tempPath
            }



            try {
                [System.IO.File]::WriteAllLines($SaveToFile, $lines)
                Write-Host "ASCII output saved to: $SaveToFile"
            } catch {
                throw "Failed to write to file: '$SaveToFile'. Check permissions."
            }
        } else {
            $lines
        }
    } catch {
        Write-Error $_
    }
}