Cmdlet

Add-OfficeExcelImage

Aliases: ExcelImage

Module: PSWriteOffice
Aliases: ExcelImage
Inputs: OfficeIMO.Excel.ExcelDocument System.Object
Outputs: OfficeIMO.Excel.ExcelImage
Source: AddOfficeExcelImageCommand.cs:49 Edit on GitHub

Embeds a file, HTTP image or reusable visual at a worksheet cell or range.

Syntax

Add-OfficeExcelImage
[-Address <String>]
[-AltText <String>]
[-Decorative]
[-Document <ExcelDocument>]
[-EndOffsetX <OfficeLength>]
[-EndOffsetY <OfficeLength>]
[-Height <OfficeLength>]
[-Name <String>]
[-NoLockAspectRatio]
[-OffsetX <OfficeLength>]
[-OffsetY <OfficeLength>]
[-PassThru]
[-Path] <String>
[-Placement <MoveAndSize|MoveOnly|FreeFloating>]
[-Rotation <Double>]
[-Scale <Double>]
[-Sheet <OfficeSheetSelector>]
[-Title <String>]
[-Width <OfficeLength>]
[<CommonParameters>]

Parameter set: Path

Add-OfficeExcelImage
[-Address <String>]
[-AltText <String>]
[-Decorative]
[-Document <ExcelDocument>]
[-EndOffsetX <OfficeLength>]
[-EndOffsetY <OfficeLength>]
[-Height <OfficeLength>]
[-Name <String>]
[-NoLockAspectRatio]
[-OffsetX <OfficeLength>]
[-OffsetY <OfficeLength>]
[-PassThru]
[-Placement <MoveAndSize|MoveOnly|FreeFloating>]
[-Rotation <Double>]
[-Scale <Double>]
[-Sheet <OfficeSheetSelector>]
[-Title <String>]
-Url <Uri>
[-Width <OfficeLength>]
[<CommonParameters>]

Parameter set: Url

Add-OfficeExcelImage
[-Address <String>]
[-AltText <String>]
[-Decorative]
[-Document <ExcelDocument>]
[-EndOffsetX <OfficeLength>]
[-EndOffsetY <OfficeLength>]
[-Height <OfficeLength>]
[-Id <String>]
-InputObject <Object>
[-MaximumSvgElements <Int32>]
[-MaximumSvgViewportDimension <Double>]
[-MaximumSvgViewportPixelCount <Int64>]
[-Name <String>]
[-NoLockAspectRatio]
[-OffsetX <OfficeLength>]
[-OffsetY <OfficeLength>]
[-PassThru]
[-Placement <MoveAndSize|MoveOnly|FreeFloating>]
[-PointsPerPixel <Double>]
[-Rotation <Double>]
[-Scale <Double>]
[-Sheet <OfficeSheetSelector>]
[-SvgPolicy <PreserveVector|RasterizeWhenNeeded|RequireVector>]
[-Title <String>]
[-Width <OfficeLength>]
[<CommonParameters>]

Parameter set: Visual

Description

A cell uses a one-cell anchor; a range uses a two-cell anchor. Numbers mean points and unit suffixes are accepted. With no dimensions or Scale, file images retain their detected size. Range anchors determine their own size. URL downloads use the native network policy and cancellation token.

Examples

Place a logo at its natural size.

ExcelSheet 'Cover' { ExcelImage -Path ./logo.png -Address A1 -AltText 'Contoso' }

Pin a reusable visual to the report header.

$visual | ExcelImage -Document $book -Sheet Summary -Address B2:G12 -Name Health

Download and resize a status badge.

ExcelImage -Url https://status.example.com/badge.png -Address H1 -Width 4cm

Add a logo

New-OfficeExcel -Path .\Reports\Q3-Sales.xlsx {
    ExcelSheet 'Cover' {
        ExcelImage .\Assets\Logo.png -Address A1 -AltText 'Northwind Traders logo'
    }
}

Places the company logo at A1 of the cover sheet at its natural size.

Fit a site photo into a range

Open-OfficeExcel -Path .\Facilities\Inspection-Gdansk.xlsx {
    ExcelSheet 'Findings' {
        ExcelImage .\Photos\Gdansk-Roof-0412.jpg -Address D2:J20 -Placement MoveAndSize -AltText 'Roof drainage at the Gdansk warehouse'
    }
}

Stretches an inspection photo across D2:J20 so it moves and resizes with the cells.

Add an image from a URL

Open-OfficeExcel -Path .\Reports\Status.xlsx {
    ExcelSheet 'Summary' {
        ExcelImage -Url https://status.example.com/badge/production.png -Address H1 -Width 4cm -AltText 'Production status'
    }
}

Downloads a published status badge and places it at a fixed width on the summary sheet.

Parameters

-Address String optional: A1 cell or range; defaults to A1. Use B2:B2 for a two-cell anchor over one cell.
-AltText String optional: Accessible image description; omitted visual descriptions are retained.
-Decorative SwitchParameter optional: Clear accessible title and description and mark the image decorative.
-Document ExcelDocument optionalpipeline: True (ByValue): Workbook to modify outside the Excel DSL.
-EndOffsetX OfficeLength optional: Horizontal end-marker offset for a range anchor; numbers mean points.
-EndOffsetY OfficeLength optional: Vertical end-marker offset for a range anchor; numbers mean points.
-Height OfficeLength optional: Optional output height; numbers mean points and unit suffixes are accepted.
-Name String optional: Drawing name in Excel's selection pane.
-NoLockAspectRatio SwitchParameter optional: Allow interactive aspect-ratio changes in Excel; the default locks the ratio.
-OffsetX OfficeLength optional: Horizontal start-marker offset; numbers mean points.
-OffsetY OfficeLength optional: Vertical start-marker offset; numbers mean points.
-PassThru SwitchParameter optional: Return the native editable ExcelImage.
-Path String requiredposition: 0sets: Path: Literal local image path.
-Placement ExcelImagePlacement optional: Movement and resizing behavior of a two-cell anchor.; Possible values: MoveAndSize, MoveOnly, FreeFloating
-Rotation Double optional: Clockwise rotation in degrees.
-Scale Double optional: Positive percentage of the source size; exclusive with dimensions and range anchors.
-Sheet OfficeSheetSelector optional: Sheet name, one-based position or native worksheet belonging to Document.
-Title String optional: Optional title for an SVG file input.
-Width OfficeLength optional: Optional output width; numbers mean points and unit suffixes are accepted.
-Url Uri requiredsets: Url: HTTP or HTTPS image URI; local files use Path.
-Id String optionalsets: Visual: Optional stable identifier for an SVG file input.
-InputObject Object requiredpipeline: True (ByValue)sets: Visual: ChartForgeX artifact, OfficeVisualSource, prepared visual or SVG path.
-MaximumSvgElements Int32 optionalsets: Visual: Optional OfficeIMO SVG import element limit.
-MaximumSvgViewportDimension Double optionalsets: Visual: Optional maximum SVG viewport width or height. Increase the safe default only for trusted input.
-MaximumSvgViewportPixelCount Int64 optionalsets: Visual: Optional maximum SVG viewport area in pixels. Increase the safe default only for trusted input.
-PointsPerPixel Double optionalsets: Visual: Conversion factor from ChartForgeX pixels to Office points.
-SvgPolicy OfficeVisualSvgPolicy optionalsets: Visual: SVG fidelity policy used by OfficeIMO.ChartForgeX.; Possible values: PreserveVector, RasterizeWhenNeeded, RequireVector

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.