Command

New-ImageChart

Module imageplayground

Inputs

ChartForgeX.Core.Chart ImagePlayground.ChartDefinition[]

Outputs

ChartForgeX.Core.Chart

Creates an image chart from definitions.

Syntax

New-ImageChart [-Annotation <Object[]>] [-AnnotationsDefinition <ScriptBlock>] [-Background <ChartColor>] [-ChartsDefinition] <ScriptBlock> [-Dpi <Double>] -FilePath <String> [-Height <Int32>] [-Options <ChartRenderOptions>] [-PassThru] [-SecondaryYTitle <String>] [-Show] [-ShowGrid] [-Subtitle <String>] [-Theme <ChartTheme>] [-Title <String>] [-Watermark <VisualWatermark[]>] [-Width <Int32>] [-XLabel <String[]>] [-XTitle <String>] [-YTitle <String>] [<CommonParameters>]

Parameter set: ScriptBlock

New-ImageChart [-Annotation <Object[]>] [-AnnotationsDefinition <ScriptBlock>] [-Background <ChartColor>] -ChartScript <ScriptBlock> [-Dpi <Double>] -FilePath <String> [-Height <Int32>] [-Options <ChartRenderOptions>] [-PassThru] [-SecondaryYTitle <String>] [-Show] [-ShowGrid] [-Subtitle <String>] [-Theme <ChartTheme>] [-Title <String>] [-Watermark <VisualWatermark[]>] [-Width <Int32>] [-XLabel <String[]>] [-XTitle <String>] [-YTitle <String>] [<CommonParameters>]

Parameter set: ChartScript

New-ImageChart [-Annotation <Object[]>] [-AnnotationsDefinition <ScriptBlock>] [-Background <ChartColor>] -Chart <Chart> [-Dpi <Double>] -FilePath <String> [-Height <Int32>] [-Options <ChartRenderOptions>] [-PassThru] [-SecondaryYTitle <String>] [-Show] [-ShowGrid] [-Subtitle <String>] [-Theme <ChartTheme>] [-Title <String>] [-Watermark <VisualWatermark[]>] [-Width <Int32>] [-XLabel <String[]>] [-XTitle <String>] [-YTitle <String>] [<CommonParameters>]

Parameter set: Chart

New-ImageChart [-Annotation <Object[]>] [-AnnotationsDefinition <ScriptBlock>] [-Background <ChartColor>] -Definition <ChartDefinition[]> [-Dpi <Double>] -FilePath <String> [-Height <Int32>] [-Options <ChartRenderOptions>] [-PassThru] [-SecondaryYTitle <String>] [-Show] [-ShowGrid] [-Subtitle <String>] [-Theme <ChartTheme>] [-Title <String>] [-Watermark <VisualWatermark[]>] [-Width <Int32>] [-XLabel <String[]>] [-XTitle <String>] [-YTitle <String>] [<CommonParameters>]

Parameter set: Definition

Description

Use this cmdlet to render one or more chart definitions into a final image file.

Examples

Authored help example

Create a simple bar chart and save it

New-ImageChart -ChartsDefinition {
    New-ImageChartBar -Name 'Q1' -Value 12,18,25 -Color CornflowerBlue
    New-ImageChartBar -Name 'Q2' -Value 14,20,28 -Color Orange
} -FilePath chart.png -XTitle 'Month' -YTitle 'Revenue'

Builds chart definitions inside a script block and renders them into a PNG file.

Create a line chart with annotations and preview it

$defs = @(
    New-ImageChartLine -Name 'CPU' -Value 35,42,58,61,49 -Color LimeGreen -Smooth
)
$ann = @(
    New-ImageChartAnnotation -X 3 -Y 61 -Text 'Peak' -Arrow
)
New-ImageChart -Definition $defs -Annotation $ann -FilePath cpu-usage.png -Theme Dark -ShowGrid -Show

Renders a themed line chart and overlays an annotation highlighting the peak value.

Title, category labels, and stacked bars from CSV data

$builds = Import-Csv builds.csv   # Day, Passed, Failed
New-ImageChart -Title 'Builds by result' -Subtitle 'Week 41' -XLabel $builds.Day -FilePath builds.png -Options (New-ImageChartOptions -BarLayout Stacked -ShowLegend) {
    New-ImageChartBar -Name Passed -Value $builds.Passed
    New-ImageChartBar -Name Failed -Value $builds.Failed
}

Titles, category labels, and the bar layout are parameters, so the chart never needs to be modified through .NET methods.

Bars and a target line on one chart, saved as WebP

New-ImageChart -XLabel Mon, Tue, Wed, Thu, Fri -FilePath latency.webp {
    New-ImageChartBar -Name Requests -Value 410, 380, 455, 520, 470
    New-ImageChartLine -Name 'p95 (ms)' -Value 182, 175, 240, 310, 205 -Marker Circle -SecondaryAxis
} -SecondaryYTitle 'p95 (ms)'

Bar, line, area, scatter, and similar cartesian definitions can be mixed; markers and axes are set per series.

Parameters

-Annotation Object[] optional: Annotations for the chart.
-AnnotationsDefinition ScriptBlock optional: ScriptBlock producing annotations.
-Background ChartColor optional: Chart background color.
-ChartsDefinition ScriptBlock requiredposition: 0sets: ScriptBlock: ScriptBlock producing chart definitions.
-Dpi Double optional: PNG physical resolution metadata in dots per inch.
-FilePath String required: The extension picks the format: .png, .svg, .html, or .htm use the ChartForgeX renderers; .jpg, .jpeg, .webp, .gif, .bmp, .tif, .tiff, and .tga encode the same pixels through ImagePlayground. Relative paths resolve against the current PowerShell location.
-Height Int32 optional: Height of the chart in pixels.
-Options ChartRenderOptions optional: Renderer options created by New-ImageChartOptions.
-PassThru SwitchParameter optional: Write the ChartForgeX chart to the pipeline after rendering.
-SecondaryYTitle String optionalaliases: Y2Title: Title of the secondary (right) Y axis used by series created with -SecondaryAxis.
-Show SwitchParameter optional: Open the image after creation.
-ShowGrid SwitchParameter optional: Display grid lines.
-Subtitle String optional: Supporting chart heading. Supply an empty string to clear a supplied chart's subtitle.
-Theme ChartTheme optional: Chart theme.; Possible values: Default, Dark, Light, Colorblind, Aurora, Editorial, Candy, PeopleInfographic, Terminal, TransparentOverlayDark, Minimal, DashboardLight, SaasDashboardLight, RestaurantDashboardLight
-Title String optional: Chart heading. A supplied native chart keeps its heading unless this parameter is supplied.
-Watermark VisualWatermark[] optional: Watermarks applied to static SVG, HTML, or PNG output.
-Width Int32 optional: Width of the chart in pixels.
-XLabel String[] optionalaliases: Categories, Category, XLabels: Values at positions 1, 2, 3... of each series are labelled with these entries in order.
-XTitle String optional: X axis title.
-YTitle String optional: Y axis title.
-ChartScript ScriptBlock requiredsets: ChartScript: The script block receives the chart as its first argument and can mutate it directly or return a replacement chart.
-Chart Chart requiredpipeline: True (ByValue)sets: Chart: ChartForgeX chart object to render.
-Definition ChartDefinition[] requiredpipeline: True (ByValue)sets: Definition: Typed definitions produced by New-ImageChart data cmdlets, supplied directly or through the pipeline.

Common Parameters

This command supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable.

For more information, see about_CommonParameters.