Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,15 @@ on:
- 'docfx.json'
- '.config/dotnet-tools.json'
- 'src/PlaIO/**'
- 'src/PlaIO.Scene/**'
- '.github/workflows/docs.yml'
pull_request:
paths:
- 'docs/**'
- 'docfx.json'
- '.config/dotnet-tools.json'
- 'src/PlaIO/**'
- 'src/PlaIO.Scene/**'
- '.github/workflows/docs.yml'
workflow_dispatch:

Expand Down
40 changes: 25 additions & 15 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,17 @@ jobs:
if ($env:GITHUB_REF_NAME -cne "v$($version.Trim())") {
throw "The release tag must match the package version v$($version.Trim())."
}
# Before anything is published: a tag whose commit has no changelog section for the version fails here.
- name: Extract release notes
shell: pwsh
run: |
$version = $env:GITHUB_REF_NAME.Substring(1)
$changelog = Get-Content -LiteralPath CHANGELOG.md -Encoding utf8
$start = [array]::FindIndex($changelog, [Predicate[string]] { param($line) $line.StartsWith("## [$version]") })
if ($start -lt 0) { throw "CHANGELOG.md has no entry for $version" }
$notes = @()
for ($i = $start + 1; $i -lt $changelog.Count -and -not $changelog[$i].StartsWith('## ['); $i++) { $notes += $changelog[$i] }
$notes | Set-Content -LiteralPath release-notes.md -Encoding utf8
- run: dotnet restore PlaIO.slnx
- run: dotnet build PlaIO.slnx -c Release --no-restore
- run: dotnet test PlaIO.slnx -c Release --no-build
Expand All @@ -41,21 +52,8 @@ jobs:
with:
name: packages
path: artifacts/*
- name: Create release
shell: pwsh
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
$version = $env:GITHUB_REF_NAME.Substring(1)
$changelog = Get-Content -LiteralPath CHANGELOG.md -Encoding utf8
$start = [array]::FindIndex($changelog, [Predicate[string]] { param($line) $line.StartsWith("## [$version]") })
if ($start -lt 0) { throw "CHANGELOG.md has no entry for $version" }
$notes = @()
for ($i = $start + 1; $i -lt $changelog.Count -and -not $changelog[$i].StartsWith('## ['); $i++) { $notes += $changelog[$i] }
$notes | Set-Content -LiteralPath release-notes.md -Encoding utf8
$files = @(Get-ChildItem artifacts -File | ForEach-Object { $_.FullName })
gh release create $env:GITHUB_REF_NAME --title $env:GITHUB_REF_NAME --notes-file release-notes.md @files
if ($LASTEXITCODE -ne 0) { throw "gh release create failed with exit code $LASTEXITCODE" }
# The push comes before the GitHub release: a refused first publication of a package id can be fixed and the
# job run again, because --skip-duplicate makes the push repeatable and no release exists yet.
# Trusted publishing: the NuGet policy for this repository and workflow file exchanges the GitHub OIDC token for a short-lived key.
- uses: NuGet/login@v1
id: nuget-login
Expand All @@ -68,3 +66,15 @@ jobs:
dotnet nuget push $package.FullName --api-key '${{ steps.nuget-login.outputs.NUGET_API_KEY }}' --source https://api.nuget.org/v3/index.json --skip-duplicate
if ($LASTEXITCODE -ne 0) { throw "dotnet nuget push failed for $($package.Name) with exit code $LASTEXITCODE" }
}
- name: Create release
shell: pwsh
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
$version = $env:GITHUB_REF_NAME.Substring(1)
$files = @(Get-ChildItem artifacts -File | ForEach-Object { $_.FullName })
# A version with a hyphen is a prerelease.
$flags = @()
if ($version.Contains('-')) { $flags += '--prerelease' }
gh release create $env:GITHUB_REF_NAME --title $env:GITHUB_REF_NAME --notes-file release-notes.md @flags @files
if ($LASTEXITCODE -ne 0) { throw "gh release create failed with exit code $LASTEXITCODE" }
17 changes: 17 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,23 @@ All notable changes are documented here. The format follows [Keep a Changelog](h
and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html); versions before 1.0 may change the
API between minor releases.

## [Unreleased]

### Added

- The `PlaIO.Scene` adapter project (namespace `PlaIO.Scene`): `PlaSceneReader.Read(path)` turns a `.pla` or `.pln`
container into an `IOScene` `SceneDocument` — one model per file with the frozen `Key` derivation (the
`PlaSceneOptions.ModelKey`, else the file name), no elements yet (the container reader does not decode element
contents), and the `container-only` diagnostic. The project is `IsPackable=false` and is not published; it ships on a
`PlaIO` release tag when the reader decodes elements and geometry. See `docs/scene.md`.

### Changed

- The release workflow follows the IOExtend release order: the NuGet packages are pushed before the GitHub release is
created (a refused first publication can be fixed and the job re-run, because `--skip-duplicate` makes the push
repeatable), and a tag whose version contains a hyphen is published as a prerelease. The changelog section for the
version is checked before anything is published.

## [0.1.0] - 2026-11-12

### Added
Expand Down
7 changes: 5 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,8 +100,11 @@ Write commit messages in the imperative mood, for example,
## Releases

Push a tag matching the package version, such as `v0.1.0`, to run `release.yml`.
The workflow builds and tests the solution, attaches packages, symbols, source and checksums to a GitHub release published at once (not a draft),
and publishes the NuGet packages through Trusted Publishing. The release notes are the section of `CHANGELOG.md` for the version, so add that section before the tag.
The workflow builds and tests the solution, packs it, and pushes the NuGet packages first, through Trusted Publishing
(`--skip-duplicate` makes a repeated run idempotent). Only then does it attach packages, symbols, source and checksums
to a GitHub release published at once (not a draft). A tag whose version contains a hyphen, such as `v0.2.0-preview.1`,
is published as a prerelease. This is the IOExtend release order: NuGet first, the GitHub release second.
The release notes are the section of `CHANGELOG.md` for the version, so add that section before the tag.
The NuGet policy must name this repository (`IOExtend/PlaIO`), `release.yml`, the configured NuGet profile and the `PlaIO*` package pattern.
The repository variable `NUGET_USER` must hold the name of that NuGet profile; the workflow reads it for the Trusted Publishing login.

Expand Down
6 changes: 6 additions & 0 deletions Directory.Packages.props
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,12 @@

<!-- Runtime dependencies of the library: none. See docs/dependencies.md. -->

<ItemGroup>
<!-- The scene contract of PlaIO.Scene: any patch of the 0.1 line, no preview of the next (breaking) minor that
IOScene publishes. -->
<PackageVersion Include="IOScene" Version="[0.1.1, 0.2.0-0.0)" />
</ItemGroup>

<ItemGroup>
<!-- Build-time only. -->
<PackageVersion Include="Microsoft.SourceLink.GitHub" Version="10.0.403" />
Expand Down
1 change: 1 addition & 0 deletions PlaIO.slnx
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
<Folder Name="/src/">
<Project Path="src/PlaIO/PlaIO.csproj" />
<Project Path="src/PlaIO.Cli/PlaIO.Cli.csproj" />
<Project Path="src/PlaIO.Scene/PlaIO.Scene.csproj" />
</Folder>
<Project Path="tests/PlaIO.Tests/PlaIO.Tests.csproj" />
</Solution>
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,12 @@
PlaIO is a pure managed .NET library and command line tool that reads the container of Archicad project files (`.pla`,
`.pln`) and the cover image of BIMx files (`.bimx`) directly from disk, without Archicad and without native dependencies.

In the [IOExtend](https://github.com/IOExtend) ecosystem PlaIO is a leaf engine: it depends on no other IOExtend package
and on no scene type. The `PlaIO.Scene` adapter in this repository turns an Archicad container into an `IOScene` scene
document for [IOViewer](https://github.com/IOExtend/IOViewer) and coordination tools; while the reader decodes only the
container, the scene holds one model and no elements, and the adapter is not published yet — it ships on a `PlaIO`
release tag when the reader decodes elements and geometry (see [the scene adapter](docs/scene.md)).

## What it does

- Detects the file kind from the first bytes: the container shared by `.pla` and `.pln`, or `.bimx`.
Expand Down
3 changes: 2 additions & 1 deletion docfx.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,8 @@
"metadata": [
{
"src": [
{ "src": "src/PlaIO", "files": ["PlaIO.csproj"] }
{ "src": "src/PlaIO", "files": ["PlaIO.csproj"] },
{ "src": "src/PlaIO.Scene", "files": ["PlaIO.Scene.csproj"] }
],
"dest": "docs/api",
"properties": { "TargetFramework": "net10.0" },
Expand Down
12 changes: 8 additions & 4 deletions docs/dependencies.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,11 @@ Build settings shared by every project live in `Directory.Build.props`; the SDK
## Runtime packages (library and tool)

None. The library and the command line tool use only the .NET base class library, so the published packages bring no
third-party code with them.
third-party code with them. No engine package depends on another IOExtend package.

The `PlaIO.Scene` adapter (not published yet) depends on [`IOScene`](https://github.com/IOExtend/IOScene)
`[0.1.1, 0.2.0-0.0)`: any patch of the IOScene 0.1 line, no preview of the next (breaking) minor. `IOScene` itself has
no dependencies.

## Build-time packages

Expand All @@ -19,7 +23,7 @@ It is referenced by every project with `PrivateAssets` all, so it is not a depen

## Test packages

Pinned to exact versions: Microsoft.NET.Test.Sdk 18.11.0, xunit 2.9.3 and xunit.runner.visualstudio 4.0.1.
Pinned to exact versions: Microsoft.NET.Test.Sdk 18.12.0, xunit 2.9.3 and xunit.runner.visualstudio 4.0.1.
They are referenced only by `tests/PlaIO.Tests`, which is not packed.

## Auditing
Expand All @@ -42,5 +46,5 @@ Re-run the audit when changing dependencies.
and `ContinuousIntegrationBuild` true when `CI`, `GITHUB_ACTIONS` or `TF_BUILD` is set. It also sets `PathMap` on every
build, not only on CI, so the folder of the build machine does not appear in PDBs and binaries. `src/Directory.Build.props`
and `tests/Directory.Build.props` import it and set `TreatWarningsAsErrors` true; the tests file also turns
`GenerateDocumentationFile` off. The library generates its XML documentation file, which feeds the
[API reference](api/PlaIO.yml). The library, the CLI and the tests target `net8.0` and `net10.0`.
`GenerateDocumentationFile` off. The library and the adapter generate their XML documentation files, which feed the
[API reference](api/PlaIO.yml). The library, the CLI, the adapter and the tests target `net8.0` and `net10.0`.
42 changes: 42 additions & 0 deletions docs/scene.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
# The scene adapter

`PlaIO.Scene` (namespace `PlaIO.Scene`) turns an Archicad container read by PlaIO into an `IOScene`
[`SceneDocument`](https://github.com/IOExtend/IOScene/blob/main/docs/contract.md) — the neutral scene model that
[IOViewer](https://github.com/IOExtend/IOViewer) and the coordination tools consume. The adapter uses only the public
API of the `PlaIO` library and depends on the exact `PlaIO` version it ships with.

## What the scene holds today

- One `SceneModel` for the file: `Key` and `Name` (see [Frozen derivations](#frozen-derivations)), `SourceFormat`
(`pla` or `pln`, the lower-case file extension) and `Producer` (`PlaIO.Scene <version>`).
- No elements, no geometry, no property sets: the container reader does not decode element contents yet. Mode 2 (LZ)
payloads, the meaning of the object directory records and the class names are research items (repository issues #7,
#8, #9). The scene holds no guesses: what cannot be read exactly is not written, and the `container-only` diagnostic
says so.

A geometry-free scene file is a valid scene document: a consumer that reads it shows the model with no content to draw.

## Frozen derivations

The consumers of a scene store `SceneModel.Key` together with the source id of an element, so a change of the
derivation is a breaking release of `PlaIO.Scene`:

- `Key` is `PlaSceneOptions.ModelKey` when given; otherwise the file name with its extension, without its directory.
- The key never switches to a better identifier. A better identifier, once the format gives the adapter one, goes into
a new `SceneModel` member, not into the key.

The identity tests of the derivation are in `tests/PlaIO.Tests/PlaSceneReaderTests.cs`.

## Diagnostics

| Severity | Code | Meaning |
|---|---|---|
| Info | `container-only` | The reader decodes the container only: elements, properties and geometry are not read yet, so the scene has no elements. |

## Publication

The project is `IsPackable=false` and is not published on NuGet: it ships on a `PlaIO` release tag, with an exact
`[X.Y.Z]` dependency on `PlaIO` and an `IOScene [0.1.1, 0.2.0-0.0)` range, when the reader decodes elements and
geometry — the adapter trigger of the [target architecture](https://github.com/IOExtend/.github/blob/main/profile/README.md)
("PlaIO decodes geometry / has elements to export / has a writer"). Until then nothing publishes, so no consumer can
build on an empty mapping.
2 changes: 2 additions & 0 deletions docs/toc.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@
href: public-api.md
- name: Command line and exit codes
href: cli.md
- name: Scene adapter
href: scene.md
- name: Dependencies
href: dependencies.md
- name: Private test fixtures
Expand Down
34 changes: 34 additions & 0 deletions src/PlaIO.Scene/PlaIO.Scene.csproj
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
<Project Sdk="Microsoft.NET.Sdk">

<PropertyGroup>
<Description>Turns Archicad containers read by PlaIO into IOScene scene documents. Unpublished while the reader decodes only the container; it ships when elements and geometry are read.</Description>
<TargetFrameworks>net8.0;net10.0</TargetFrameworks>
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<!-- The adapter trigger of the target architecture: it becomes packable and ships on a PlaIO tag when the reader
decodes elements and geometry. Until then nothing publishes, so no consumer can build on an empty mapping. -->
<IsPackable>false</IsPackable>
<!-- IOScene is referenced by a range whose upper bound is a prerelease ([0.N.0, 0.N+1.0-0.0)); NU5104 is expected. -->
<NoWarn>$(NoWarn);NU5104</NoWarn>
</PropertyGroup>

<ItemGroup>
<ProjectReference Include="..\PlaIO\PlaIO.csproj" />
<PackageReference Include="IOScene" />
</ItemGroup>

<!-- The shared pack metadata expects icon.png beside the project; the adapter ships the engine's icon. -->
<ItemGroup>
<None Remove="$(MSBuildProjectDirectory)/icon.png" />
<None Include="..\PlaIO\icon.png" Pack="true" PackagePath="/" Visible="false" />
</ItemGroup>

<!-- Adapter and engine ship on one tag, so the packed engine dependency is exact [X.Y.Z], not >=; a mix gives NU1608. -->
<Target Name="PinProjectReferencesExactly" AfterTargets="_GetProjectReferenceVersions">
<ItemGroup>
<_Pinned Include="@(_ProjectReferencesWithVersions)"><ProjectVersion>[%(_ProjectReferencesWithVersions.ProjectVersion)]</ProjectVersion></_Pinned>
<_ProjectReferencesWithVersions Remove="@(_ProjectReferencesWithVersions)" />
<_ProjectReferencesWithVersions Include="@(_Pinned)" />
</ItemGroup>
</Target>

</Project>
10 changes: 10 additions & 0 deletions src/PlaIO.Scene/PlaSceneOptions.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
namespace PlaIO.Scene;

/// <summary>Options of <see cref="PlaSceneReader"/>.</summary>
public sealed class PlaSceneOptions
{
/// <summary>The key of the model in the scene (<c>SceneModel.Key</c>). Together with the source ids of the elements it
/// identifies an element outside the scene once the adapter writes them, so it must stay the same for every conversion
/// of one file. Null takes the file name with its extension, without its directory.</summary>
public string? ModelKey { get; set; }
}
65 changes: 65 additions & 0 deletions src/PlaIO.Scene/PlaSceneReader.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
using System.Reflection;
using IOScene;

namespace PlaIO.Scene;

/// <summary>
/// Turns an Archicad container (a .pla or .pln file) into a scene (<see cref="SceneDocument"/>): one model for the file,
/// without elements, properties or geometry while the container reader does not decode them yet.
/// </summary>
/// <remarks>
/// <para>The model's <c>Key</c> is the <see cref="PlaSceneOptions.ModelKey"/>, else the file name without its directory.
/// The derivation is frozen: the key never switches to a better identifier, and the elements this adapter will write get
/// their persisted identity from it. <c>SourceFormat</c> is the lower-case file extension (<c>pla</c> or <c>pln</c>),
/// <c>Producer</c> this assembly's name and version.</para>
/// <para>The scene holds no guesses: what the container reader cannot decode yet (element contents, class names, the
/// meaning of the object directory records) is not written, and the <c>container-only</c> diagnostic says so.</para>
/// </remarks>
public static class PlaSceneReader
{
private const int ModelId = 1;

/// <summary>Reads the container at <paramref name="path"/> and turns it into a scene.</summary>
/// <exception cref="ArgumentException"><paramref name="path"/> is empty, or <see cref="PlaSceneOptions.ModelKey"/> is empty.</exception>
public static PlaSceneResult Read(string path, PlaSceneOptions? options = null)
{
ArgumentException.ThrowIfNullOrEmpty(path);
string key = options?.ModelKey ?? Path.GetFileName(path);
if (key.Length == 0) throw new ArgumentException("The model key is empty.", nameof(options));
return Map(path, key);
}

private static PlaSceneResult Map(string path, string key)
{
using var document = PlaDocument.Open(path);
var scene = new SceneDocument { Title = key };
scene.Models.Add(new SceneModel
{
Id = ModelId,
Key = key,
Name = key,
SourceFormat = SourceFormat(path),
Producer = Producer,
});
return new PlaSceneResult
{
Document = scene,
Diagnostics =
[
new(SceneSeverity.Info, "container-only",
"The reader decodes the container only: elements, properties and geometry are not read yet, so the scene has no elements."),
],
};
}

private static string? SourceFormat(string path)
{
string extension = Path.GetExtension(path).TrimStart('.').ToLowerInvariant();
return extension is "pla" or "pln" ? extension : null;
}

/// <summary>"PlaIO.Scene" and the version of this assembly without the source revision.</summary>
private static string Producer { get; } = "PlaIO.Scene " + (typeof(PlaSceneReader).Assembly
.GetCustomAttribute<AssemblyInformationalVersionAttribute>()?.InformationalVersion.Split('+')[0]
?? typeof(PlaSceneReader).Assembly.GetName().Version?.ToString(3));
}
14 changes: 14 additions & 0 deletions src/PlaIO.Scene/PlaSceneResult.cs
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
using IOScene;

namespace PlaIO.Scene;

/// <summary>The scene made from one Archicad container by <see cref="PlaSceneReader"/>, and what the read reported.</summary>
public sealed class PlaSceneResult
{
/// <summary>The scene: one model, without elements while the reader decodes only the container.</summary>
public required SceneDocument Document { get; init; }

/// <summary>What the scene does not hold yet: <c>container-only</c> while elements, properties and geometry are not
/// read. Empty when the container was read whole.</summary>
public IReadOnlyList<SceneDiagnostic> Diagnostics { get; init; } = [];
}
2 changes: 2 additions & 0 deletions tests/PlaIO.Tests/PlaIO.Tests.csproj
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@

<ItemGroup>
<ProjectReference Include="..\..\src\PlaIO\PlaIO.csproj" />
<!-- The scene adapter is tested here too, like RvtIO.Scene is tested in RvtIO.Tests. -->
<ProjectReference Include="..\..\src\PlaIO.Scene\PlaIO.Scene.csproj" />
<!-- The command line of the tool, compiled here to test it without starting a process. -->
<Compile Include="..\..\src\PlaIO.Cli\Cli.cs" Link="Cli\Cli.cs" />
<Compile Include="..\..\src\PlaIO.Cli\DirectoryJson.cs" Link="Cli\DirectoryJson.cs" />
Expand Down
Loading
Loading