Aioros.Graphs 0.1.0-preview.2

Aioros.Graphs

Preview. Aioros.Graphs is in public preview: its APIs can change between versions, and it is not ready for production yet.

The chart engine of the Aioros ecosystem, as three packages: Aioros.Graphs, Aioros.Graphs.Svg and Aioros.Graphs.Avalonia.

What charts need, in C#: arrays, scales, shapes, curves, paths, number and time formats, following d3, the reference its tests compare with. It has no UI dependency: shapes write path commands into a sink, and two sinks ship with it, SVG path data in UTF-8 for the web (Aioros records self-drawn controls as SVG) and native geometry for the desktop. Chart libraries are built on it in their own repositories: Aioros.Pictor, charts in pure XAML, first.

Aioros.Graphs is an independent port and is not affiliated with or endorsed by the d3 project. d3 (ISC) and d3-sankey (BSD-3-Clause) keep their notices in THIRD-PARTY-NOTICES.md, which every package carries.

Two goals, in this order:

1. The same output as d3. Every ported function is tested against fixtures generated by d3 itself (tools/golden): ticks, scale values and tick labels bit for bit, SVG path data byte for byte.
2. Performance. Structs and spans on the hot paths, shapes specialized at compile time for their curve and sink (no virtual calls, no closures, no LINQ), pooled buffers, no allocation per point (bench).

var x = LinearScale.Create([0, data.Length - 1], [0, 960]);
var y = LinearScale.Create([min, max], [500, 0]).Nice();
x.Map(index, xs);
y.Map(values, ys);

var buffer = new ArrayBufferWriter<byte>();
var svg = new SvgPathWriter(buffer);
Line.Write(ref svg, Curve.MonotoneX, xs, ys);
// buffer.WrittenSpan is d3's line().curve(curveMonotoneX)(data), byte for byte

var geometry = new StreamGeometry();
using (var context = geometry.Open())
{
    var sink = new GeometrySink(context);
    Line.Write(ref sink, Curve.MonotoneX, xs, ys);
    sink.Complete();
}
// the same path as a StreamGeometry

What is ported

The rest is listed in docs/roadmap.md; precedents and decisions are in docs/decisions.md.

Layout

dotnet build Aioros.Graphs.slnx
dotnet test --solution Aioros.Graphs.slnx
dotnet run -c Release --project bench/Aioros.Graphs.Benchmarks -- --filter '*'

Using a local build

Until the engine is published to nuget.org, the repositories built on it (Aioros.Pictor, and any later chart library) consume it from a local package folder:

1. Pack it: eng/pack.sh writes Aioros.Graphs, Aioros.Graphs.Svg and Aioros.Graphs.Avalonia (with their .snupkg symbols) to artifacts/packages/ and prints the copy command. eng/pack.sh dev.3 packs a distinct prerelease (0.1.0-dev.3) so a consumer picks up a new build without clearing its cache.
2. Copy the .nupkg files into the consumer's packages/ folder (committed or ignored, as that repository decides).
3. List the folder in the consumer's nuget.config:

<configuration>
  <packageSources>
    <add key="local" value="packages" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
</configuration>

4. Reference the packages as usual (<PackageReference Include="Aioros.Graphs" Version="0.1.0-preview.2" />).

Once the engine is finished and published, the consumers drop the local source and take the packages from nuget.org. The version has one source, VersionPrefix and VersionSuffix in Directory.Build.props.

License and attribution

The ported code follows d3 by Mike Bostock, ISC-licensed, and d3-sankey, BSD-3-Clause; its notice is in THIRD-PARTY-NOTICES.md. The engine itself is MIT-licensed, as the whole Aioros ecosystem: see LICENSE.