ImagePlayground - visual automation for PowerShell and .NET

ImagePlayground turns scripts and application data into finished visual assets. Process photographs, inspect or remove metadata, create QR codes and barcodes, render charts and dashboards, map systems and organizations, or publish animated terminal and source-to-result stories without opening an image editor.

NuGet package

PowerShell module

Project information

Start here: install · quick start · feature guide · PowerShell commands · examples · generated reference

Why ImagePlayground

Automation often ends with something a person must read: a chart in a report, a service map in an incident, a QR code on a device, a sanitized image for publication, or an animated terminal session in documentation. ImagePlayground keeps those results reproducible.

The PowerShell module provides one scripting surface over reusable .NET libraries:

• ImagePlayground provides the editable image wrapper and file workflows.
• OfficeIMO.Core handles managed raster decoding, filters, transforms, metadata, and pixel comparison.
• ChartForgeX handles charts, topology, hierarchy, and raster primitives. ChartForgeX.Visuals handles composition, visual blocks, and canvases; ChartForgeX.Stories handles animation encoding and story rendering.
• CodeGlyphX handles QR-code and barcode generation and decoding.

PowerShell users install one module. .NET applications reference only the package that owns the capability they need.

See what it produces

These are real outputs generated with the module in this repository.

Canvases and announcement graphics Compose fixed-size social cards, wallpapers, covers, labels, information tiles, and branded backdrops.	Topology and system maps Render grouped services, databases, routes, statuses, ports, details, scenarios, and interactive HTML diagrams.
Charts and report visuals Build business charts, statistical plots, gauges, progress visuals, heatmaps, treemaps, waterfalls, and annotations.	Animated terminal stories Turn authored commands or captured output into SVG, HTML, PNG, GIF, or APNG without executing displayed code.

What ImagePlayground covers

Area	What you can produce	Start with
Image processing	Resized, cropped, rotated, adjusted, blurred, sharpened, converted, compared, merged, watermarked, annotated, or Base64-encoded images	Resize-Image, New-ImageCrop, Set-ImageAdjust, ConvertTo-Image
Image composition	Thumbnails, avatars, icons, mosaics, grids, animated GIFs, social cards, covers, and wallpapers	New-ImageThumbnail, New-ImageAvatar, New-ImageMosaic, New-ImageCanvas
Metadata and provenance	EXIF, XMP, IPTC, ICC, C2PA container discovery, direct XMP AI declarations, HEIF information, exports, imports, updates, and controlled removal	Get-ImageMetadata, Get-ImageProvenance, Remove-ImageMetadata
QR codes and barcodes	General QR content, contact, Wi-Fi, calendar, email, OTP, payment, cryptocurrency, phone, SMS, location, and common barcode workflows	New-ImageQRCode, New-ImageQRCodeWiFi, New-ImageBarCode, Get-ImageQRCode
Charts	Static or portable chart output from typed PowerShell definitions or native ChartForgeX charts	New-ImageChart, New-ImageChartLine, New-ImageChartBar, New-ImageChartOptions
Dashboards and visual blocks	Metric cards, lists, tables, timelines, charts, and mixed grids rendered together	New-ImageVisualGrid, New-ImageMetricCard, New-ImageTableBlock
Topology and hierarchy	Service maps, dependency diagrams, organization charts, grouped nodes, ports, diagnostics, scenarios, and route motion	New-ImageTopology, Get-ImageTopologyDiagnostics, New-ImageOrganizationChart
Visual stories	Console sessions, source-to-result scenes, declared outcomes, motion cues, watermarks, and portable semantic artifacts	New-ImageConsoleStory, New-ImageStory, New-ImageVisualStory, ConvertTo-ImageVisualArtifact

The generated PowerShell reference contains every cmdlet, parameter set, example, input contract, and output contract.

PowerShell and .NET entry points

Task	PowerShell	.NET owner
Load, manipulate, and save images	Get-Image, Save-Image, focused *-Image* commands	ImagePlayground.Image, ImagePlayground.ImageHelper
Inspect or remove metadata	Get-ImageMetadata, Get-ImageProvenance, Remove-ImageMetadata	ImagePlayground.ImageHelper metadata and provenance APIs
Create or decode QR codes and barcodes	New-ImageQRCode*, New-ImageBarCode, Get-ImageQRCode, Get-ImageBarCode	CodeGlyphX
Build charts	New-ImageChart and New-ImageChart* definitions	ChartForgeX.Core.Chart
Compose dashboards and canvases	New-ImageVisualGrid, New-ImageCanvas, visual-block commands	ChartForgeX.VisualBlocks, ChartForgeX.VisualCanvas
Map systems and organizations	New-ImageTopology, New-ImageOrganizationChart	ChartForgeX topology and hierarchy APIs
Publish console or visual stories	New-ImageConsoleStory, New-ImageStory, New-ImageVisualStory	ChartForgeX terminal and visual-story APIs
Hand visuals to another workflow	ConvertTo-ImageVisualArtifact, Export-ImageVisualArtifact	ChartForgeX visual artifacts

Installation

PowerShell

ImagePlayground supports Windows PowerShell 5.1 and PowerShell 7+.

Install-Module -Name ImagePlayground -Scope CurrentUser
Import-Module ImagePlayground

To update an existing installation:

Update-Module -Name ImagePlayground

.NET

Install the core package for image loading and processing:

dotnet add package ImagePlayground

Add the owning package when the application also needs charts, topology, QR codes, or barcodes:

dotnet add package ChartForgeX
dotnet add package CodeGlyphX

The ImagePlayground .NET package uses OfficeIMO.Core for raster processing, ChartForgeX.Visuals for composition, and ChartForgeX.Stories for GIF/APNG encoding. Its ChartForgeX dependencies use the same 3.0.0 version. The PowerShell module also exposes ChartForgeX charts and stories and CodeGlyphX QR codes and barcodes.

Quick start

Process and publish an image

Resize-Image `
    -FilePath '.\photo.jpg' `
    -OutputPath '.\photo-small.jpg' `
    -Width 1200

Add-ImageWatermark `
    -FilePath '.\photo-small.jpg' `
    -OutputPath '.\photo-published.jpg' `
    -WatermarkPath '.\logo.png' `
    -Placement BottomRight `
    -Opacity 0.7

Get-ImageMetadata -FilePath '.\photo-published.jpg'

Create and verify a QR code

New-ImageQRCode `
    -Content 'https://evotec.xyz' `
    -FilePath '.\evotec-qr.png'

$decoded = Get-ImageQRCode -FilePath '.\evotec-qr.png'
$decoded.Text

Render a chart

New-ImageChart {
    New-ImageChartBar -Name 'Healthy' -Value 18 -Color MediumSeaGreen
    New-ImageChartBar -Name 'Warning' -Value 3 -Color Orange
    New-ImageChartBar -Name 'Failed' -Value 1 -Color IndianRed
} -FilePath '.\service-health.png' -Width 720 -Height 420 -ShowGrid

Resize an image from .NET

using ImagePlayground;

ImageHelper.Resize(
    filePath: "photo.jpg",
    outFilePath: "photo-small.jpg",
    width: 1200,
    height: null,
    keepAspectRatio: true);

Image processing and composition

ImagePlayground uses the managed raster APIs in OfficeIMO.Core, composition in ChartForgeX.Visuals, and GIF/APNG encoding in ChartForgeX.Stories. Image APIs expose owned value types and buffers. See the migration guide for type, assembly, comparison, and format changes.

Focused commands for one operation

Set-ImageAdjust `
    -FilePath '.\photo.jpg' `
    -OutputPath '.\photo-balanced.jpg' `
    -Brightness 1.05 `
    -Contrast 1.1 `
    -Saturation 1.08

New-ImageCrop `
    -FilePath '.\photo-balanced.jpg' `
    -OutputPath '.\photo-square.jpg' `
    -X 120 -Y 40 -Width 900 -Height 900

ConvertTo-Image `
    -FilePath '.\photo-square.jpg' `
    -OutputPath '.\photo-square.webp'

The destination extension selects the output format. JPEG supports -Quality; WebP output is lossless by default and uses the managed lossy encoder when -Quality is supplied. PNG supports -CompressionLevel through the shared compression profiles.

Keep an image open for several edits

$image = Get-Image -FilePath '.\photo.jpg'
try {
    $image.Resize(1200, $null, $true)
    $image.Watermark(
        'Internal',
        [ImagePlayground.WatermarkPlacement]::BottomRight,
        [OfficeIMO.Drawing.OfficeColor]::White,
        28)

    Save-Image -Image $image -FilePath '.\photo-watermarked.jpg' -Quality 88
} finally {
    $image.Dispose()
}

Compare, combine, and derive images

Need	Commands
Draw text or a wrapped text box	Add-ImageText, Add-ImageTextBox
Apply an image watermark	Add-ImageWatermark
Compare two images or save a difference mask	Compare-Image
Merge images	Merge-Image
Build contact sheets or tiled output	New-ImageGrid, New-ImageMosaic
Create avatars, thumbnails, or icons	New-ImageAvatar, New-ImageThumbnail, New-ImageIcon
Build an animation from existing frames	New-ImageGif
Move image data through text workflows	ConvertTo-ImageBase64, ConvertFrom-ImageBase64

Source

Scripted text and watermark output

See the focused scripts under Examples/Images.*.ps1 and the .NET samples in Sources/ImagePlayground.Examples.

Metadata, EXIF, HEIF, and provenance

Metadata is part of the publishing workflow, not an afterthought. ImagePlayground can inspect supported profiles, export metadata for review, update selected values, and remove selected families without hiding what happened.

$metadata = Get-ImageMetadata -FilePath '.\photo.jpg'
$provenance = Get-ImageProvenance -FilePath '.\photo.jpg'

$metadata
$provenance

Export-ImageMetadata `
    -FilePath '.\photo.jpg' `
    -OutputPath '.\photo-metadata.json'

Remove-ImageMetadata `
    -FilePath '.\photo.jpg' `
    -OutputPath '.\photo-public.jpg' `
    -MetadataType Exif, Xmp `
    -PassThru

JPEG and PNG metadata removal preserves compressed pixel data where the format permits it. HEIF and HEIC cleanup is limited to EXIF and XMP.

Get-ImageProvenance discovers embedded C2PA containers and direct XMP generative-AI declarations. It does not validate C2PA signatures, trust chains, asset hashes, or the active claim. Use a conforming C2PA validator when cryptographic provenance matters.

HEIF-specific commands can inspect container information and read, set, or remove XMP packets without presenting HEIF pixel decoding as a broader image-editing guarantee.

QR codes and barcodes

The PowerShell module exposes CodeGlyphX through task-oriented commands. Create a code, save it, and read the final image back in the same workflow.

Contact

Wi-Fi

Barcode

Typed QR payloads

Payload	Command
Contact card	New-ImageQRContact
Wi-Fi network	New-ImageQRCodeWiFi
Calendar event	New-ImageQRCodeCalendar
Email draft	New-ImageQRCodeEmail
One-time password enrollment	New-ImageQRCodeOtp
Phone number or SMS	New-ImageQRCodePhoneNumber, New-ImageQRCodeSms
Geographic location	New-ImageQRCodeGeoLocation
Bitcoin or Monero payment	New-ImageQRCodeBitcoin, New-ImageQRCodeMonero
Girocode, BezahlCode, Swiss QR, or Slovenian UPN QR	New-ImageQRCodeGirocode, New-ImageQRCodeBezahlCode, New-ImageQRCodeSwiss, New-ImageQRCodeSlovenianUpnQr
Shadowsocks or Skype	New-ImageQRCodeShadowSocks, New-ImageQRCodeSkypeCall

New-ImageQRCodeWiFi `
    -SSID 'Guest WiFi' `
    -Password 'correct horse battery staple' `
    -FilePath '.\guest-wifi.png'

(Get-ImageQRCode -FilePath '.\guest-wifi.png').Text

Use New-ImageBarCode and Get-ImageBarCode for barcode generation and readback. C# applications that only need codes should reference CodeGlyphX directly.

Get-ImageBarCode returns a CodeGlyphX DetectedSymbol; read its Format and Text properties, and check HasRawBytes before reading RawBytes when exact payload bytes are needed. Use -Detailed to inspect all recognized symbols and the scan completion reason. -ScanOptions accepts the owner's format, deadline, image-limit, and accuracy settings. See the CodeGlyphX 3 migration notes for renamed formats and result contracts.

Charts and report graphics

ImagePlayground provides a PowerShell DSL over ChartForgeX. New-ImageChart renders definitions emitted by the typed chart commands, accepts definitions from the pipeline, or accepts a native ChartForgeX.Core.Chart through -Chart or the pipeline. -Definition accepts ImagePlayground.ChartDefinition[]; ordinary arrays containing results from New-ImageChart* data commands bind to this type. Arbitrary objects are rejected during parameter binding.

Charts and factual blocks use the canonical light design by default. -Theme Dark selects the matching dark colors, typography, and frame treatment; named presentation presets and explicit colors remain available. Use -Title and -Subtitle for chart headings. Exporting an existing native chart preserves its headings, size, and theme unless you supply an override.

$annotations = New-ImageChartAnnotation `
    -X 4 `
    -Y 74 `
    -Text 'Peak' `
    -Arrow

New-ImageChart {
    New-ImageChartLine `
        -Name CPU `
        -Value 31, 42, 37, 55, 74, 61 `
        -Smooth
    New-ImageChartLine `
        -Name Memory `
        -Value 48, 51, 55, 57, 60, 62 `
        -Smooth
} -Annotation $annotations `
  -Title 'Workstation health' `
  -Subtitle 'Six samples of resource usage' `
  -FilePath '.\workstation-health.svg' `
  -XTitle Sample `
  -YTitle 'Usage %' `
  -ShowGrid

Available chart definitions

• comparison and trend: bar, horizontal bar, line, smooth line, step line, area, stacked area, step area, slope, lollipop
• distribution and relationship: scatter, bubble, histogram, box plot, range band, range bar, heatmap
• part-to-whole: pie, donut, treemap, funnel, pictorial, waterfall
• status and progress: circle, radial, gauge, bullet, progress
• multidimensional and specialist: radar, polar, word cloud
• finishing: annotations, themes, backgrounds, grid, legend, renderer options, watermarks, and DPI metadata

The same chart definition can produce PNG, SVG, or standalone HTML where the selected renderer supports it. See Examples/Charts.ChartForgeX.Showcase.ps1.

Canvases, dashboards, and visual blocks

Use a canvas when every element needs an explicit position. Use a visual grid when charts and reusable blocks should flow into dashboard panels. Canvas light/dark themes use the same canonical color and font roles; explicit layer colors and background overrides are retained.

Fixed canvas

Compact grid export

Fixed canvas

New-ImageCanvas `
    -Preset SocialPreview `
    -Theme Dark `
    -Title 'Service health' `
    -LayerDefinition {
        New-ImageCanvasText `
            -X 72 -Y 72 -Width 1000 `
            -Text 'Service health' `
            -FontSize 58 -Color White -Emphasized

        New-ImageCanvasInfoTile `
            -X 72 -Y 190 -Width 380 -Height 150 `
            -Icon API -Label Requests -Value '12,840' `
            -Detail '+12% this week' `
            -MiniChartKind Area -MiniValues 2, 4, 5, 8
    } `
    -FilePath '.\release-preview.png'

Dashboard grid

$theme = 'Light'
New-ImageVisualGrid `
    -Title 'Service health' `
    -Subtitle 'Generated from PowerShell objects' `
    -Columns 2 `
    -Theme $theme `
    -ContentDefinition {
        New-ImageMetricCard `
            -Label Requests -Value 12840 -Trend '+12%' `
            -Status Positive -MiniValues 8, 9, 10, 12 -Theme $theme

        New-ImageListBlock `
            -Title Checks -Item API, Database `
            -Status Positive, Warning -Theme $theme

        New-ImageTableBlock `
            -Title Services `
            -Theme $theme `
            -Column Name, Status `
            -Row @(
                @{ Name = 'API'; Status = 'Healthy' }
                @{ Name = 'Database'; Status = 'Warning' }
            )

        New-ImageTimelineBlock -Title Activity -Theme $theme -ItemDefinition {
            New-ImageTimelineItem `
                -Kind Event -Title 'Build completed' `
                -Timestamp '14:20' -Status Positive
            New-ImageTimelineItem `
                -Kind ChecklistItem -Title 'Smoke tests' -Completed
        }
    } `
    -FilePath '.\service-health.svg'

Omit -FilePath to retain a reusable grid and pass it to New-ImageVisualStory or a native ChartForgeX canvas.

HTML grids reflow their panels on narrow screens. SVG and PNG grids keep their authored dimensions: reducing a wide image also reduces its text. For a compact fixed export, compose one column with blocks sized for that destination instead. VisualGrid.ServiceHealth.ps1 exports a reflowing HTML page, a wide fixed grid, and a separate 368px compact grid in either theme. Canvas.SocialPreview.ps1 demonstrates the same distinction for positioned canvases. Canvas text without -Color follows the selected canvas foreground; explicitly supplied white, transparent and custom colors remain unchanged.

Topology, scenarios, and organization charts

Topology commands model the system first and render it second. Nodes can belong to groups, expose named ports and detail rows, carry status, and connect through typed edges. Scenarios can highlight an ordered route through the same topology.

New-ImageTopology -TopologyDefinition {
    New-ImageTopologyGroup `
        -Id edge -Label 'Edge Site' -Status Healthy

    New-ImageTopologyNode `
        -Id gateway -Label Gateway -Kind Network `
        -Status Healthy -GroupId edge -Symbol GW

    New-ImageTopologyNode `
        -Id api -Label 'App API' -Kind Service `
        -Status Healthy -GroupId edge -Symbol API

    New-ImageTopologyNode `
        -Id database -Label Database -Kind Database `
        -Status Warning -GroupId edge -Symbol SQL

    New-ImageTopologyEdge `
        -SourceNodeId gateway -TargetNodeId api `
        -Label HTTPS -Kind Connectivity -Status Healthy `
        -Direction Forward

    New-ImageTopologyEdge `
        -SourceNodeId api -TargetNodeId database `
        -Label '32 ms' -Kind Dependency -Status Warning `
        -Direction Forward
} -Title 'Service topology' `
  -Layout Layered `
  -Direction LeftToRight `
  -Theme Dark `
  -FitContentToViewport `
  -FilePath '.\service-topology.png'

Choose PNG or SVG for static assets, HTML for interactive scenarios, and GIF or APNG when route motion should be sampled into an animation. Get-ImageTopologyDiagnostics exposes prepared geometry and routing evidence when a complex diagram needs inspection.

Organization charts use a separate hierarchy-focused surface. See Examples/Organization.Engineering.ps1 for a complete branch-oriented hierarchy.

Console stories

Console stories present a terminal session without coupling documentation to a screen recorder or executing the command shown in the story.

$story = New-ImageConsoleStory `
    -WindowStyle WindowsTerminal `
    -Width 980 `
    -Speed Fast `
    -Content {
        New-ImageConsoleStoryTab `
            -Id PowerShell -Title PowerShell `
            -Profile PowerShell -Active

        New-ImageConsoleStoryCommand `
            -Text 'Invoke-EnvironmentAudit.ps1'

        New-ImageConsoleStoryOutput `
            -Text '12 checks passed' -Style Success

        New-ImageConsoleStoryOutput `
            -Text 'Report saved to audit.json' -Style Muted

        New-ImageConsoleStoryPause -Seconds 0.6
    }

$story | Export-ImageConsoleStory -Path '.\audit.svg'
$story | Export-ImageConsoleStory `
    -Path '.\audit.gif' `
    -FramesPerSecond 8 `
    -EndHoldSeconds 1

The story can contain typed commands, output, tables, blank lines, pauses, palettes, persistent tabs, and explicit tab switches. A new tab can open in the foreground or be staged in the background. Returning to a tab keeps its transcript.

For a real run, execute the script explicitly and feed captured output into the story:

$transcript = & .\Invoke-EnvironmentAudit.ps1 2>&1 |
    Out-String -Stream -Width 110

$story = $transcript | New-ImageConsoleStory `
    -CommandText '.\Invoke-EnvironmentAudit.ps1' `
    -Dialect PowerShell `
    -Theme PowerShell `
    -WindowStyle Minimal

$story | Export-ImageConsoleStory -Path '.\audit.svg'

New-ImageConsoleStory never executes -CommandText.

Source-to-result and animated visual stories

Generic stories combine resolved source, terminal output, text, images, and SVG into timed scenes. Declared outcomes must be visible in the completed scene, so a story that promises a chart cannot finish with only “Saved chart.png.”

New source-to-result stories use the canonical dark surfaces and syntax roles. Supply -ThemeMode Light for a light story. Charts, canvases, grids, diagrams and stories share the paired immutable ChartForgeX.Themes.VisualTheme; a separate VisualThemeMode chooses its light or dark colors. Terminal Light and Dark selections use the same design roles; named PowerShell, Ubuntu, Campbell and other shell palettes remain distinct. Custom themes and already-authored native stories retain their selected styling on export.

$chartPath = '.\weekly-builds.png'
$sourceText = @'
$options = New-ImageChartOptions -TickCount 4
New-ImageChart {
    New-ImageChartLine -Name Builds `
        -Value 12, 18, 15, 24, 31
} -Theme Light -Width 560 -Height 320 `
    -Title 'Weekly builds' `
    -FilePath '.\weekly-builds.png' `
    -Options $options
'@

$options = New-ImageChartOptions -TickCount 4
New-ImageChart {
    New-ImageChartLine -Name Builds -Value 12, 18, 15, 24, 31
} -Title 'Weekly builds' -Theme Light -FilePath $chartPath -Width 560 -Height 320 -Options $options

$source = ConvertTo-ImageStorySource `
    -Text $sourceText `
    -Language PowerShell

$codePanel = New-ImageStoryPanel -Id code -Source $source
$chartPanel = New-ImageStoryPanel `
    -Id chart -MediaPath $chartPath `
    -AccessibleText 'Weekly builds chart'

$writeScene = New-ImageStoryScene `
    -Id write -Title 'Write the chart' -Panels $codePanel
$resultScene = New-ImageStoryScene `
    -Id result -Title 'See the chart' -Layout Split `
    -Panels $codePanel, $chartPanel
$outcome = New-ImageStoryOutcome `
    -Id chart -Label 'Weekly builds visible' `
    -PanelId chart

New-ImageStory `
    -Title 'Weekly builds recipe' `
    -ThemeMode Light `
    -Scenes $writeScene, $resultScene `
    -Outcomes $outcome `
    -FilePath '.\chart-story.gif'

PowerShell source highlighting uses the PowerShell parser. C# and Bash can use the optional ImagePlayground.Syntax.TreeSitter package. There is no regex-coloring fallback and no Tree-sitter native payload in the normal PowerShell module.

Use New-ImageVisualStory when a visual grid should reveal blocks through named motion cues. SVG and HTML preserve script-free animation; PNG, print, and reduced-motion output show the complete final state.

The profile and terminal examples include separately authored compact versions. Terminal widths start at 480 design pixels; an SVG can scale below that size, but its text scales with it. Choose the compact composition when readability at a small viewing size matters.

Story.ChartInFiveLines.ps1 also authors a stacked compact story titled “Weekly builds recipe.” Its multiline recipe uses short lines and a taller source panel, while a separately sized chart keeps the result labels readable.

For an animated editor, pass a StorySourceTimeline to New-ImageStoryPanel -SourceTimeline. -SourceOptions sets the filename, line numbers, wrapping, and fixed font size. For captured sessions, New-ImageStoryReplay accepts ordered dictionaries or JSON objects with TimestampSeconds, Kind, and event-specific fields:

$events = @(
    @{ TimestampSeconds = 0; Kind = 'Command'; Text = './Test-Project.ps1' }
    @{ TimestampSeconds = 20; Kind = 'Output'; Text = '24 checks passed'; Tone = 'Success' }
)
$recording = New-ImageStoryReplay -DurationSeconds 25 -Events $events
$replay = $recording.CompressPauses([TimeSpan]::FromSeconds(2))
$panel = New-ImageStoryPanel -Id terminal -Replay $replay `
    -TerminalOptions ([ChartForgeX.Stories.VisualStoryTerminalOptions]::new(18))
$scene = New-ImageStoryScene -Id result -Title 'Replay the result' `
    -DurationSeconds $replay.Duration.TotalSeconds -Panels $panel
$outcome = New-ImageStoryOutcome -Id passed -Label '24 checks passed' -PanelId terminal
New-ImageStory -Title 'Project validation' -Scenes $scene -Outcomes $outcome `
    -FilePath './validation.html' -Player -PlayCount 1 -EndHoldSeconds 2

Replay events also support ReplaceLine, Clear, Directory, Marker, OpenTab, and SelectTab. Commands remain observations. Execute trusted scripts explicitly before capturing their results. Trim and CompressPauses return edited presentations with original timestamps; trimming keeps earlier context in the transcript. Explain adds presentation annotations.

New-ImageStory prepares once for its primary output and portable bundle. -EndHoldSeconds, -TransitionSeconds, -PlayCount, -FramesPerSecond, -AnimationScale, and -MaximumFrames share playback and sampling settings across animated outputs. -Player adds controls to HTML; HTML is script-free when omitted. GIF accepts at most 50 frames per second and requires a rounded final delay of at least 20 milliseconds. APNG supports up to 60 frames per second. PNG remains the completed poster. An export error leaves an existing output file intact; each successfully exported bundle artifact commits independently.

Story.WriteFixReplay.ps1 captures an actual PowerShell error and corrected result, animates the source correction, and creates a player with SVG, PNG, GIF, APNG, and transcript artifacts. MP4 integration is deferred.

Story.ScriptAndOutput.ps1 is a reusable starter for your own script and saved output. It types the source with syntax colors, pauses on the completed script, and reveals the output line by line. The default export uses a macOS dark appearance and includes square (720×720), portrait (720×1280), and widescreen (1280×720) versions, each with a GIF, HTML player, completed PNG, transcript, and story manifest.

Import-Module ImagePlayground
./Examples/Story.ScriptAndOutput.ps1 -ScriptPath ./demo.ps1 -OutputPath ./output.txt `
    -Title 'My PowerShell demo' -Appearance MacOS -ColorMode Dark -OutputDirectory ./stories

Choose -Appearance MacOS, Windows or Linux for coordinated editor and replay windows with desktop gradients; Graphite keeps minimal chrome. -ColorMode Dark or Light changes surfaces and syntax colors. PowerShell tokens are resolved before playback, so colored characters appear during typing without executing source or reparsing each frame. Appearance changes the presentation, while the displayed language and captured output remain PowerShell.

Supply UTF-8 files, or use -ScriptText and -OutputText for inline strings. Capture output separately from a script you trust; the starter never executes the displayed source. Its replay timing is authored from the saved lines. Use -WritingSeconds, -ReadingSeconds, -ReplaySeconds, and -EndHoldSeconds to change pacing; -FontSize sets readable source and terminal text, and -Formats Square,Portrait selects layouts. -PlayCount 1 plays once; the default loops. Existing exports require -Overwrite or a different destination. Keep input files outside the physical destination and all linked export paths. The starter checks every requested layout before writing, including directory, file and hard-link aliases. Destination environment variables expand once; use a directly resolved path when a variable contains another variable reference.

Use the GIF for a short silent social post. For a narrated video, open the widescreen HTML player, restart playback, and record it with your usual video capture tool. Use the portrait player for a vertical video. Long scripts and output scroll within fixed-font viewports; split lengthy demonstrations into focused stories so viewers can read each step.

Portable visual artifacts and Office workflows

ConvertTo-ImageVisualArtifact attaches static SVG and versioned semantic JSON bytes to a pipeline object. The SVG is suitable for flat placement; the semantic payload lets a compatible consumer rebuild editable shapes and connectors.

$artifact = New-ImageTopology -TopologyDefinition {
    New-ImageTopologyNode -Id api -Label API -Kind Service
    New-ImageTopologyNode -Id database -Label Database -Kind Database
    New-ImageTopologyEdge `
        -Id api-db -SourceNodeId api -TargetNodeId database `
        -Label queries
} -FilePath '.\topology.svg' -PassThru |
    ConvertTo-ImageVisualArtifact `
        -Id service-topology `
        -Title 'Service topology'

$artifact | Export-ImageVisualArtifact -FilePath '.\topology-artifact.svg'

When PSWriteOffice is installed, the same artifact can become an editable Visio diagram:

$artifact | Export-OfficeVisioVisual -Path '.\topology.vsdx'

ImagePlayground owns the PowerShell-facing visual artifact. PSWriteOffice owns Office and Visio document creation.

Complete PowerShell command map

The current module exports 131 compiled cmdlets and two compatibility aliases. The groups below keep the full surface discoverable without turning the quick start into an alphabetical reference dump.

Image processing and files

• Add-ImageText, Add-ImageTextBox, Add-ImageWatermark
• Compare-Image, ConvertFrom-ImageBase64, ConvertTo-Image, ConvertTo-ImageBase64
• Get-Image, Merge-Image, Resize-Image, Save-Image
• New-ImageAvatar, New-ImageCrop, New-ImageGif, New-ImageGrid, New-ImageIcon, New-ImageMosaic, New-ImageThumbnail
• Set-ImageAdjust, Set-ImageBlur, Set-ImageRotation, Set-ImageSharpen

Metadata and provenance

• Clear-ImageThumbnailCache, Export-ImageMetadata, Import-ImageMetadata
• Get-ImageExif, Get-ImageMetadata, Get-ImageProvenance
• Get-ImageHeifInfo, Get-ImageHeifXmp
• Remove-ImageExif, Remove-ImageHeifXmp, Remove-ImageMetadata
• Set-ImageExif, Set-ImageHeifXmp

QR codes and barcodes

• Get-ImageBarCode, Get-ImageQRCode, New-ImageBarCode, New-ImageQRCode
• New-ImageQRContact, New-ImageQRCodeCalendar, New-ImageQRCodeEmail, New-ImageQRCodeGeoLocation, New-ImageQRCodeOtp, New-ImageQRCodePhoneNumber, New-ImageQRCodeSms, New-ImageQRCodeWiFi
• New-ImageQRCodeBezahlCode, New-ImageQRCodeBitcoin, New-ImageQRCodeGirocode, New-ImageQRCodeMonero, New-ImageQRCodeShadowSocks, New-ImageQRCodeSkypeCall, New-ImageQRCodeSlovenianUpnQr, New-ImageQRCodeSwiss

Charts

• New-ImageChart, New-ImageChartOptions, New-ImageChartAnnotation
• New-ImageChartArea, New-ImageChartBar, New-ImageChartBarOptions, New-ImageChartHorizontalBar, New-ImageChartLine, New-ImageChartLollipop, New-ImageChartSlope, New-ImageChartStackedArea, New-ImageChartStepArea, New-ImageChartStepLine
• New-ImageChartBoxPlot, New-ImageChartBubble, New-ImageChartHeatmap, New-ImageChartHistogram, New-ImageChartRangeBand, New-ImageChartRangeBar, New-ImageChartScatter
• New-ImageChartDonut, New-ImageChartFunnel, New-ImageChartPictorial, New-ImageChartPie, New-ImageChartTreemap, New-ImageChartWaterfall
• New-ImageChartBullet, New-ImageChartCircle, New-ImageChartGauge, New-ImageChartProgress, New-ImageChartRadial
• New-ImageChartPolar, New-ImageChartRadar, New-ImageChartWordCloud

Canvases and visual blocks

• New-ImageCanvas, New-ImageCanvasInfoTile, New-ImageCanvasText
• New-ImageListBlock, New-ImageMetricCard, New-ImageTableBlock, New-ImageTimelineBlock, New-ImageTimelineItem
• New-ImageVisualGrid, New-ImageVisualGridItem

Topology and organization

• Get-ImageTopologyDiagnostics, New-ImageTopology
• New-ImageTopologyEdge, New-ImageTopologyGroup, New-ImageTopologyNode, New-ImageTopologyNodeDetail, New-ImageTopologyNodePort
• New-ImageTopologyMotion, New-ImageTopologyScenario, New-ImageTopologyScenarioStep
• New-ImageOrganizationChart, New-ImageOrganizationMember

Console stories

• New-ImageConsoleStory, Export-ImageConsoleStory
• New-ImageConsoleStoryBlankLine, New-ImageConsoleStoryCommand, New-ImageConsoleStoryOutput, New-ImageConsoleStoryPause, New-ImageConsoleStoryTable
• New-ImageConsoleStoryPalette, New-ImageConsoleStoryTab, Select-ImageConsoleStoryTab

Visual stories and artifacts

• ConvertTo-ImageStorySource, New-ImageStory, New-ImageStoryOutcome, New-ImageStoryPanel, New-ImageStoryScene
• New-ImageVisualMotionCue, New-ImageVisualStory, New-ImageVisualWatermark
• ConvertTo-ImageVisualArtifact, Export-ImageVisualArtifact

Compatibility aliases remain available as New-QRCode and New-QRCodeWiFi. New scripts should use the New-Image* names.

Get-Command -Module ImagePlayground |
    Sort-Object Noun, Verb

.NET API

The core package targets .NET Standard 2.0, .NET Framework 4.7.2, .NET 8, and .NET 10.

using ImagePlayground;
using OfficeIMO.Drawing;

using var image = ImagePlayground.Image.Load("photo.jpg");
image.Resize(1200, null, keepAspectRatio: true);
image.Watermark(
    "Internal",
    WatermarkPlacement.BottomRight,
    OfficeColor.White,
    fontSize: 28);
image.Save("photo-watermarked.jpg");

Choose the package that owns the job

Need	Package
Image loading, processing, composition, metadata, thumbnails, icons, mosaics, avatars, or GIFs	ImagePlayground
Charts, topology, hierarchy, and raster primitives	ChartForgeX
Composition, visual blocks, canvases, and watermark decoration	ChartForgeX.Visuals
Stories, terminal playback, motion, and GIF/APNG encoding	ChartForgeX.Stories
QR codes, barcodes, GS1 data, renderers, or image decoding	CodeGlyphX
PowerShell access to all three owners	ImagePlayground module

Output and interoperability

Surface	Typical output
Image processing	PNG, JPEG, WebP, GIF, BMP, PBM, TGA, TIFF, and ICO output selected by extension; supported managed codec subsets for loading
Charts and static report visuals	PNG and SVG, with standalone HTML where supported
Topology	PNG, SVG, interactive HTML, GIF, and APNG
Console stories	SVG, HTML, PNG, GIF, and APNG
Generic and animated visual stories	SVG, HTML, PNG, GIF, and APNG where supported by the selected renderer
Visual artifacts	Static SVG plus versioned semantic JSON bytes

PowerShell commands have one execution path. Commands that can use asynchronous file APIs do so internally and honor pipeline cancellation; there is no -Async switch because a PowerShell invocation still completes before control returns to the caller.

Example library

Workflow	Example
Image adjustments, crop, rotation, text, watermark, metadata, thumbnails, mosaic, and conversion	Examples/Images.*.ps1
QR codes and barcodes	Examples/QrCode.ps1, Examples/QrCodeWithLogo.ps1, Examples/Barcode.Create.ps1
Chart gallery	Examples/Charts.ChartForgeX.Showcase.ps1
Social preview canvas	Examples/Canvas.SocialPreview.ps1
Light/dark service-health dashboard and compact fixed export	Examples/VisualGrid.ServiceHealth.ps1
Service topology and route animation	Examples/Topology.ServiceMap.ps1, Examples/Topology.RouteAnimation.ps1
Organization hierarchy	Examples/Organization.Engineering.ps1
Console stories and compact terminal presentation	Examples/ConsoleStory.PowerShell.ps1, Examples/ConsoleStory.TabNavigation.ps1, Examples/ConsoleStory.CapturedScript.ps1
Animated grid with a compact composition	Examples/VisualStory.Profile.ps1
Generic source-to-result story	Examples/Story.ChartInFiveLines.ps1

The curated Website examples provide shorter source-to-result walkthroughs. The generated command reference contains at least one example for every exported cmdlet.

Documentation

• Generated PowerShell command reference
• Website documentation
• Workflow selection guide
• Charts, topology, and visual reporting
• PowerShell example scripts
• .NET example project
• HEIC support investigation

Generated command Markdown and external help come from the C# XML documentation through PSPublishModule/PowerForge. Update the source comments and regenerate instead of editing command pages by hand.

Compatibility and current boundaries

• PowerShell: Windows PowerShell 5.1 and PowerShell 7+
• Core library: .NET Standard 2.0, .NET Framework 4.7.2, .NET 8, and .NET 10
• Raster processing, metadata, and comparison engine: OfficeIMO.Core
• Chart and topology engine: ChartForgeX; canvas and composition engine: ChartForgeX.Visuals; story and animation engine: ChartForgeX.Stories
• QR-code and barcode engine: CodeGlyphX
• Optional C# and Bash source highlighting: ImagePlayground.Syntax.TreeSitter

HEIF and HEIC commands inspect container data and manage EXIF/XMP paths described by their command documentation. HEIC pixel decoding and HEVC encoding are unsupported; AVIF loading accepts the documented managed decoder subset.

Breaking changes in 3.0

ImagePlayground 3.0 removed the PowerShell -Async parameter and the Windows-only ImagePlayground.Gdi project. Invoke asynchronous-capable commands normally.

The PowerShell module keeps chart-definition, topology, QR-code, and barcode commands as thin adapters. C# callers should use ChartForgeX or CodeGlyphX directly for those capabilities.

Troubleshooting

The installed module has fewer commands than this repository

Get-Module -ListAvailable ImagePlayground |
    Sort-Object Version -Descending |
    Select-Object -First 1 Name, Version, Path

Get-Command -Module ImagePlayground |
    Sort-Object Name

Repository source, an open branch, the PowerShell Gallery package, and the version installed on a machine are separate release states.

A QR code or barcode was created but does not scan

Decode the final saved artifact with Get-ImageQRCode or Get-ImageBarCode, then test the real device or application that must consume it. Styling and image composition can affect scanability even when the payload itself is valid.

A topology or story looks different in PNG and HTML

PNG represents the completed static state. HTML and SVG may retain interaction or motion. Reduced-motion and print output intentionally expose the final readable state rather than hiding content behind animation.

A complex topology needs layout evidence

Use -IncludeLayoutDiagnostics with New-ImageTopology or inspect the prepared result with Get-ImageTopologyDiagnostics before changing node coordinates or routing options blindly.

Build and test

dotnet build .\Sources\ImagePlayground.sln --configuration Release
dotnet test .\Sources\ImagePlayground.Tests\ImagePlayground.Tests.csproj --configuration Release
pwsh -File .\ImagePlayground.Tests.ps1

For a local source-module session:

dotnet build `
    .\Sources\ImagePlayground.PowerShell\ImagePlayground.PowerShell.csproj `
    --configuration Debug `
    --framework net8.0

$env:IMAGEPLAYGROUND_DEVELOPMENT = '1'
Import-Module .\ImagePlayground.psd1 -Force

Author and community

License

ImagePlayground is available under the MIT License.