OfficeIMO.ChartForgeX 3.4.4

OfficeIMO.ChartForgeX

OfficeIMO.ChartForgeX is the optional bridge for placing any ChartForgeX VisualArtifact in Word, Excel, PowerPoint, PDF, or another OfficeDrawing consumer, and for projecting supported diagram semantics into native editable Visio. Existing OfficeIMO packages do not acquire a ChartForgeX dependency.

For source builds, reference OfficeIMO.ChartForgeX.csproj from the consuming project and make the ChartForgeX source projects available through the repository's project-reference configuration. The bridge remains optional: applications that do not reference it keep the standard OfficeIMO dependency graph.

Every CFX surface that emits SVG can use the flat Office placement path, even when it does not expose a typed artifact envelope. Wrap the generated markup in OfficeVisualSource:

OfficeVisualConversionResult visual = new OfficeVisualSource(canvas.ToSvg()) {
    Id = "release-overview",
    Title = "Release overview",
    AlternativeText = "Release readiness summary with six status tiles."
}.ToOfficeVisual();

The bridge renders once and returns an OfficeVisualConversionResult containing:

• SVG or PNG placement bytes for Word, Excel, and PowerPoint, according to the selected SVG policy;
• an OfficeDrawing scene for PDF and drawing pipelines;
• dimensions normalized to points;
• accessible text, metadata-ready regions, and a typed fidelity report.

using ChartForgeX.VisualArtifacts;
using OfficeIMO.ChartForgeX;

VisualArtifact artifact = chart.ToVisualArtifact("sales-quarter");
artifact.Accessibility.WithTextAlternative(
    "Quarterly sales",
    "Revenue increased in each of the four reported quarters.");

OfficeVisualConversionResult visual = artifact.ToOfficeVisual(
    new OfficeVisualConversionOptions {
        WidthPoints = 420,
        SvgPolicy = OfficeVisualSvgPolicy.RasterizeWhenNeeded
    });

paragraph.AddVisualArtifact(visual);
sheet.AddVisualArtifact(2, 2, visual);
slide.AddVisualArtifact(visual, leftPoints: 36, topPoints: 72);

PdfDocument.Create(pdf => pdf.Content(content =>
    content.AddVisualArtifact(visual)), pdfOptions);

The default PreserveVector policy keeps the imported vector scene and reports SVG features that OfficeIMO.Drawing cannot represent. Choose RasterizeWhenNeeded for visual fidelity when unsupported SVG features should use the PNG placement payload, or RequireVector when incomplete vector conversion must fail closed. Word, Excel, and PowerPoint use the selected placement payload; PDF uses the converted OfficeDrawing scene.

Native editable Visio

Topology, flow, and sequence artifacts can be projected into native OfficeIMO.Visio diagrams. Nodes, containers, connectors, Shape Data, hyperlinks, sequence messages, activations, notes, and fragments remain editable after saving to VSDX. The conversion result includes the document, generated page, validated CFX interchange envelope, and a fidelity report.

using ChartForgeX.VisualArtifacts;
using OfficeIMO.ChartForgeX;

VisualArtifact artifact = topology.ToVisualArtifact();
OfficeVisioVisualConversionResult visio = artifact.ToOfficeVisio(
    new OfficeVisioVisualOptions { PageName = "Service topology" });

visio.Document.Save("service-topology.vsdx");

if (visio.Report.HasSemanticLoss) {
    foreach (OfficeVisioVisualDiagnostic diagnostic in visio.Report.Diagnostics) {
        Console.WriteLine($"{diagnostic.Code}: {diagnostic.Message}");
    }
}

AllProjectedObjectsEditable reports whether the native objects can be edited independently. HasSemanticLoss is a separate fidelity decision: it becomes true only for warning diagnostics, when Visio cannot represent a source feature exactly, even though every projected shape remains editable. Disabling Shape Data or native hyperlinks is therefore reported when source semantics would otherwise be omitted. Information diagnostics describe lossless normalizations such as collision-safe Shape Data aliases. ArtifactKind preserves how the visual was authored, while SemanticFamily identifies the reusable topology, flow, or sequence projection. Use stable diagnostic codes and severity for automation and Message for logs or user interfaces.

Pass a typed VisualArtifactInterchangeEnvelope directly when the caller shares the same ChartForgeX assembly identity. The adapter validates that object without serializing it first. Use artifact.ToInterchangeUtf8Json() and jsonBytes.ToOfficeVisio() across process or PowerShell assembly-load-context boundaries. Static SVG remains a separate fallback; the adapter does not infer editable semantics by scraping rendered markup. Unsupported artifact families fail closed for native Visio conversion. Complete topology envelopes preserve node and group bounds by default. Coordinates use PixelsPerInch to convert CFX pixels to Visio inches. Unpositioned topology, flow, and sequence inputs use native layout; UseNaturalPageSize keeps the CFX viewport as their minimum page size.

ChartForgeX owns chart and diagram semantics, deterministic rendering, interchange, watermarks, layout, and raster metadata. OfficeIMO owns document placement, native Visio projection, page layout, document/page watermarks, PDF composition, and Office package behavior.

Preserve placement and enforce fidelity

LayoutMode = Auto preserves complete topology bounds and reflows other inputs. Choose Preserve to require prepared topology coordinates, or Reflow to explicitly request native layout. Preserved graphs retain authored connector bends and named port offsets. Native titles use clear space above the preserved content; when no header band is available, the title is omitted and TitleNotProjected is reported. When the envelope has no resolved route, native routing is reported as a normalization. Native graph styling maps source card, surface, border, and foreground colors, with Arial text for portable previews. Set NativeTheme to override it, for example with VisioStyleTheme.Technical() for the previous native defaults. Curves, advanced edge styling, icons, source fonts, and complete CFX themes still have limits described by the diagnostics.

var options = new OfficeVisioVisualOptions {
    LayoutMode = OfficeVisioVisualLayoutMode.Preserve,
    PixelsPerInch = 96
};
options.RejectedDiagnostics.Add(OfficeVisioVisualDiagnosticCode.LayoutRecomputed);
var result = envelope.ToOfficeVisio(options);
result.Document.Save("topology.vsdx");

Set RequireLossless = true to reject every warning, or add selected codes to RejectedDiagnostics. A rejected conversion throws OfficeVisioVisualFidelityException; its Report explains the losses. Conversion does not save a file.

Export a report as one document

Pass an ordered sequence of envelopes to ToOfficeVisioBook. Each input becomes one page; repeated titles receive distinct page names. Each result in Pages exposes that page's fidelity report and shares the returned document.

var book = envelopes.ToOfficeVisioBook(options);
book.Document.Save("topology-report.vsdx");

ChartForgeX report pages can supply these envelopes through report.Pages.Select(page => page.ToInterchangeEnvelope()). Project CrossPageLinks into native page links to make every relationship navigable in Visio:

var envelopes = report.Pages.Select(page => page.ToInterchangeEnvelope());
var links = report.CrossPageLinks.Select(link => new OfficeVisioVisualBookLink(
    link.SourcePage, link.SourceNodeId,
    link.TargetPage, link.TargetNodeId,
    link.EdgeId));

var book = envelopes.ToOfficeVisioBookWithNavigation(links, new OfficeVisioVisualBookOptions {
    MaximumNavigationLinksPerEntity = 12,
    IncludeReturnLinks = true
});
book.Document.Save("topology-report.vsdx");

Duplicate targets are coalesced while their relationship identifiers remain in Shape Data. OmittedNavigationCount and CFX.BookLink.Omitted disclose links removed by the per-entity bound. ChartForgeX retains an original node identifier in chartforgex.sourceId whenever interchange projection has to shorten or disambiguate it, so report links still resolve against the editable Visio shape.