Skip to content

ASC FDL

ASC FDL is a toolkit for parsing, validating, creating, and transforming Framing Decision List (FDL) files. It is built around a shared C core library (libfdl_core) with idiomatic bindings for Python, TypeScript/Node.js, and C++, and conforms to the official FDL specification.

How It Works

The C++ core compiles to a shared library exporting a stable C ABI. Language bindings are auto-generated from a single IDL file (fdl_api.yaml) via a Jinja2-based code generation pipeline. This ensures Python, TypeScript, and C++ stay in sync with the C core and with each other. See Architecture for the full picture.

Install

Python

pip install asc-fdl

TypeScript / Node.js

npm install @asc-mitc/fdl

C++

The C++ bindings are a single header-only file wrapping the C ABI:

#include "fdl/fdl.hpp"

Link against libfdl_core (built via CMake from native/core/).

Features

Feature Python TypeScript C++ Notes
Parse & write FDL files Y Y Y
Validate IDs & relations Y Y Y Enforces unique IDs and valid cross-references
JSON Schema validation Y Y Y
Canvas templates Y Y Y Apply templates to produce new canvases
Rounding strategies Y Y Y Global and per-dimension rounding control
Custom attributes Y Y Y Scalar + composite types (PointFloat, DimensionsFloat, DimensionsInt)
CLI tool Y fdl-validate for command-line validation

Documentation

Section Description
Getting Started Tutorials with Python, TypeScript, and C++ examples
Architecture System design, layer diagram, ownership model
Code Generation IDL pipeline, how to extend the data model
C ABI Design Native interface contract for binding authors
Template Application Algorithm overview and formula reference
Template Implementer Guide Deep-dive with worked examples
Application Packages asc-fdl-imaging, asc-fdl-frameline-generator, asc-fdl-viewer
Contributing How to contribute, lint, test, and submit PRs

Examples

The examples/ directory contains demonstration applications:

  • examples/web_viewer/ -- A React + Express web viewer that loads and visualises FDL files using the Node.js bindings. This is a reference/demo application, not production software. It exists to validate the Node.js bindings and demonstrate library portability across language runtimes.

API Reference