northcel 0.1.0__py3-none-any.whl

northcel/__init__.py

@@ -0,0 +1,79 @@
+"""NorthCel (.ncel) — the AI-drawn video programming language."""
+
+from .config import (
+    CLI_COMMAND,
+    CLI_SHORT_ALIAS,
+    DOCS_URL,
+    FILE_EXTENSION,
+    LANGUAGE_NAME,
+    NPM_PACKAGE,
+    PACKAGE_VERSION,
+    PYPI_PACKAGE,
+    SPEC_VERSION,
+)
+from .ast_nodes import (
+    BoilSpec,
+    ColorValue,
+    DefBlock,
+    DocumentNode,
+    FilmNode,
+    LayerNode,
+    PaperSpec,
+    RibbonNode,
+    SceneNode,
+    StrokeNode,
+    SwarmNode,
+    UseNode,
+)
+from .parser import NorthCelSyntaxError, parse_ncel
+from .validator import ValidationDiagnostic, validate_document
+from .formatter import format_document
+from .rings import (
+    decode_ring_b63_1px,
+    decode_ring_q25,
+    decode_rings_payload,
+    encode_ring_b63_1px,
+    encode_ring_q25,
+    encode_rings_payload,
+)
+from .renderer import render_document_frame, render_film_frames
+
+__version__ = PACKAGE_VERSION
+
+__all__ = [
+    "LANGUAGE_NAME",
+    "FILE_EXTENSION",
+    "CLI_COMMAND",
+    "CLI_SHORT_ALIAS",
+    "PYPI_PACKAGE",
+    "NPM_PACKAGE",
+    "PACKAGE_VERSION",
+    "SPEC_VERSION",
+    "DOCS_URL",
+    "__version__",
+    "BoilSpec",
+    "ColorValue",
+    "DefBlock",
+    "DocumentNode",
+    "FilmNode",
+    "LayerNode",
+    "PaperSpec",
+    "RibbonNode",
+    "SceneNode",
+    "StrokeNode",
+    "SwarmNode",
+    "UseNode",
+    "NorthCelSyntaxError",
+    "parse_ncel",
+    "ValidationDiagnostic",
+    "validate_document",
+    "format_document",
+    "decode_ring_b63_1px",
+    "decode_ring_q25",
+    "decode_rings_payload",
+    "encode_ring_b63_1px",
+    "encode_ring_q25",
+    "encode_rings_payload",
+    "render_document_frame",
+    "render_film_frames",
+]

northcel/ast_nodes.py

@@ -0,0 +1,159 @@
+"""Typed AST nodes for NorthCel (.ncel) v0.1."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class SourceSpan:
+    line: int
+    column: int
+
+
+@dataclass(frozen=True)
+class ColorValue:
+    """Represents either a greyscale tone (0..255) or an RGB color (r, g, b)."""
+
+    r: int
+    g: int
+    b: int
+    is_grey: bool = True
+
+    @classmethod
+    def from_tone(cls, tone: int) -> "ColorValue":
+        v = int(tone)
+        return cls(r=v, g=v, b=v, is_grey=True)
+
+    @classmethod
+    def from_rgb(cls, r: int, g: int, b: int) -> "ColorValue":
+        return cls(r=int(r), g=int(g), b=int(b), is_grey=(r == g == b))
+
+    @classmethod
+    def from_hex(cls, hex_str: str) -> "ColorValue":
+        h = hex_str.lstrip("#")
+        if len(h) == 3:
+            h = "".join(c * 2 for c in h)
+        r = int(h[0:2], 16)
+        g = int(h[2:4], 16)
+        b = int(h[4:6], 16)
+        return cls(r=r, g=g, b=b, is_grey=(r == g == b))
+
+    def to_hex(self) -> str:
+        return f"#{self.r:02X}{self.g:02X}{self.b:02X}"
+
+    def as_rgb_tuple(self) -> tuple[int, int, int]:
+        return (self.r, self.g, self.b)
+
+
+@dataclass(frozen=True)
+class BoilSpec:
+    amplitude_px: float = 0.0
+    frequency: float = 1.0
+    seed_offset: int = 0
+
+
+@dataclass(frozen=True)
+class PaperSpec:
+    color: ColorValue = field(default_factory=lambda: ColorValue.from_tone(239))
+    antialias_grid: int = 4
+    grain: float = 0.0
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class LayerNode:
+    name: str
+    color: ColorValue
+    rings_count: int | None
+    payload: str
+    boil: BoilSpec | None = None
+    translate_expr: tuple[Any, Any] = (0.0, 0.0)
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class SwarmNode:
+    name: str
+    agents: int
+    color: ColorValue
+    payload: str
+    boil: BoilSpec | None = None
+    translate_expr: tuple[Any, Any] = (0.0, 0.0)
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class StrokeNode:
+    name: str
+    color: ColorValue
+    width_start: float
+    width_end: float
+    points: list[tuple[Any, Any]]
+    boil: BoilSpec | None = None
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class RibbonNode:
+    name: str
+    color: ColorValue
+    points: list[tuple[Any, Any, float]]
+    boil: BoilSpec | None = None
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class DefBlock:
+    name: str
+    params: dict[str, float]
+    items: list[LayerNode | SwarmNode | StrokeNode | RibbonNode]
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class UseNode:
+    def_name: str
+    args: dict[str, Any]
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+SceneItem = LayerNode | SwarmNode | StrokeNode | RibbonNode | UseNode
+
+
+@dataclass(frozen=True)
+class SceneNode:
+    name: str
+    width: int = 1024
+    height: int = 1024
+    fps: int = 6
+    precision: str = "0.25px"
+    seed: int = 42
+    paper: PaperSpec = field(default_factory=PaperSpec)
+    defs: dict[str, DefBlock] = field(default_factory=dict)
+    items: list[SceneItem] = field(default_factory=list)
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class FilmNode:
+    name: str
+    width: int = 1024
+    height: int = 1024
+    fps: int = 6
+    frames: int = 2
+    precision: str = "0.25px"
+    seed: int = 42
+    paper: PaperSpec = field(default_factory=PaperSpec)
+    defs: dict[str, DefBlock] = field(default_factory=dict)
+    items: list[SceneItem] = field(default_factory=list)
+    frame_overrides: dict[int, SceneNode] = field(default_factory=dict)
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))
+
+
+@dataclass(frozen=True)
+class DocumentNode:
+    spec_version: str
+    root: SceneNode | FilmNode
+    span: SourceSpan = field(default_factory=lambda: SourceSpan(1, 1))

northcel/cli.py

@@ -0,0 +1,290 @@
+"""CLI entrypoint for `northcel` and `ncel`: check, fmt, info, render, film."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+import time
+from typing import Sequence
+
+from PIL import Image
+
+from .ast_nodes import FilmNode, LayerNode, RibbonNode, SceneNode, StrokeNode, SwarmNode
+from .config import CLI_COMMAND, FILE_EXTENSION, LANGUAGE_NAME, PACKAGE_VERSION, SPEC_VERSION
+from .formatter import format_document
+from .parser import NorthCelSyntaxError, parse_ncel
+from .renderer import render_document_frame, render_film_frames
+from .rings import decode_rings_payload
+from .validator import validate_document
+
+
+def _load_and_validate(path: Path):
+    if not path.is_file():
+        return None, None, [f"1:1: error: File not found: {path}"]
+    src = path.read_text(encoding="utf-8")
+    try:
+        doc = parse_ncel(src)
+    except NorthCelSyntaxError as exc:
+        return src, None, [f"{exc.line}:{exc.column}: error: {exc.message}"]
+    diags = validate_document(doc)
+    return src, doc, diags
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    path = Path(args.file)
+    _, doc, diags = _load_and_validate(path)
+    if doc is None:
+        errors = diags
+        warnings = []
+    else:
+        errors = [d.format() for d in diags if d.level == "error"]
+        warnings = [d.format() for d in diags if d.level == "warning"]
+
+    ok = len(errors) == 0
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "ok": ok,
+                    "file": str(path),
+                    "spec_version": doc.spec_version if doc else None,
+                    "errors": errors,
+                    "warnings": warnings,
+                },
+                indent=2,
+            )
+        )
+    else:
+        for w in warnings:
+            print(f"{path}:{w}", file=sys.stderr)
+        for e in errors:
+            print(f"{path}:{e}", file=sys.stderr)
+        if ok:
+            print(f"{path}: OK ({LANGUAGE_NAME} {doc.spec_version if doc else SPEC_VERSION})")
+    return 0 if ok else 1
+
+
+def cmd_fmt(args: argparse.Namespace) -> int:
+    path = Path(args.file)
+    src, doc, diags = _load_and_validate(path)
+    if doc is None:
+        for e in diags:
+            print(f"{path}:{e}", file=sys.stderr)
+        return 1
+    errors = [d for d in diags if d.level == "error"]
+    if errors:
+        for e in errors:
+            print(f"{path}:{e.format()}", file=sys.stderr)
+        return 1
+
+    formatted = format_document(doc, include_version_header=True)
+    if args.check:
+        if src != formatted:
+            print(f"{path}: needs formatting", file=sys.stderr)
+            return 1
+        print(f"{path}: formatted")
+        return 0
+    if args.write:
+        path.write_text(formatted, encoding="utf-8")
+        print(f"{path}: formatted in-place")
+        return 0
+    sys.stdout.write(formatted)
+    return 0
+
+
+def cmd_info(args: argparse.Namespace) -> int:
+    path = Path(args.file)
+    src, doc, diags = _load_and_validate(path)
+    if doc is None:
+        for e in diags:
+            print(f"{path}:{e}", file=sys.stderr)
+        return 1
+    root = doc.root
+    total_rings = 0
+    total_vertices = 0
+    layers_summary = []
+
+    def inspect_items(items, precision: str):
+        nonlocal total_rings, total_vertices
+        for it in items:
+            if isinstance(it, (LayerNode, SwarmNode)):
+                rings = decode_rings_payload(it.payload, precision=precision)
+                v_cnt = sum(len(r) for r in rings)
+                total_rings += len(rings)
+                total_vertices += v_cnt
+                layers_summary.append(
+                    {
+                        "kind": "layer" if isinstance(it, LayerNode) else "bend_swarm",
+                        "name": it.name,
+                        "color": it.color.to_hex(),
+                        "rings": len(rings),
+                        "vertices": v_cnt,
+                    }
+                )
+            elif isinstance(it, StrokeNode):
+                total_rings += 1
+                total_vertices += len(it.points) * 2
+                layers_summary.append(
+                    {
+                        "kind": "stroke",
+                        "name": it.name,
+                        "color": it.color.to_hex(),
+                        "points": len(it.points),
+                    }
+                )
+            elif isinstance(it, RibbonNode):
+                total_rings += 1
+                total_vertices += len(it.points) * 2
+                layers_summary.append(
+                    {
+                        "kind": "ribbon",
+                        "name": it.name,
+                        "color": it.color.to_hex(),
+                        "points": len(it.points),
+                    }
+                )
+
+    inspect_items(root.items, root.precision)
+    if isinstance(root, FilmNode):
+        for f_scene in root.frame_overrides.values():
+            inspect_items(f_scene.items, f_scene.precision)
+
+    info = {
+        "file": str(path),
+        "bytes": len(src.encode("utf-8")) if src else 0,
+        "spec_version": doc.spec_version,
+        "kind": "film" if isinstance(root, FilmNode) else "scene",
+        "name": root.name,
+        "width": root.width,
+        "height": root.height,
+        "fps": root.fps,
+        "frames": root.frames if isinstance(root, FilmNode) else 1,
+        "precision": root.precision,
+        "seed": root.seed,
+        "defs": list(root.defs.keys()),
+        "total_rings": total_rings,
+        "total_vertices": total_vertices,
+        "layers": layers_summary,
+    }
+    print(json.dumps(info, indent=2))
+    return 0
+
+
+def cmd_render(args: argparse.Namespace) -> int:
+    path = Path(args.file)
+    _, doc, diags = _load_and_validate(path)
+    if doc is None:
+        for e in diags:
+            print(f"{path}:{e}", file=sys.stderr)
+        return 1
+    errors = [d for d in diags if d.level == "error"]
+    if errors:
+        for e in errors:
+            print(f"{path}:{e.format()}", file=sys.stderr)
+        return 1
+
+    t0 = time.monotonic()
+    rgb = render_document_frame(doc, frame_index=args.frame, seed_override=args.seed)
+    out_p = Path(args.out) if args.out else path.with_suffix(".png")
+    out_p.parent.mkdir(parents=True, exist_ok=True)
+    Image.fromarray(rgb, mode="RGB").save(out_p)
+    elapsed = time.monotonic() - t0
+    if args.json:
+        print(
+            json.dumps(
+                {
+                    "ok": True,
+                    "input": str(path),
+                    "output": str(out_p),
+                    "frame": args.frame,
+                    "width": int(rgb.shape[1]),
+                    "height": int(rgb.shape[0]),
+                    "seconds": round(elapsed, 4),
+                },
+                indent=2,
+            )
+        )
+    else:
+        print(f"Rendered {out_p} ({rgb.shape[1]}x{rgb.shape[0]}, frame {args.frame}) in {elapsed:.3f}s")
+    return 0
+
+
+def cmd_film(args: argparse.Namespace) -> int:
+    path = Path(args.file)
+    _, doc, diags = _load_and_validate(path)
+    if doc is None:
+        for e in diags:
+            print(f"{path}:{e}", file=sys.stderr)
+        return 1
+    errors = [d for d in diags if d.level == "error"]
+    if errors:
+        for e in errors:
+            print(f"{path}:{e.format()}", file=sys.stderr)
+        return 1
+
+    indices: list[int] | None = None
+    if args.frames:
+        if ".." in args.frames:
+            a_s, b_s = args.frames.split("..", 1)
+            indices = list(range(int(a_s), int(b_s) + 1))
+        else:
+            indices = [int(x.strip()) for x in args.frames.split(",") if x.strip()]
+
+    t0 = time.monotonic()
+    res = render_film_frames(doc, out_dir=args.out_dir, frame_indices=indices, mp4_path=args.mp4)
+    res["seconds"] = round(time.monotonic() - t0, 4)
+    print(json.dumps(res, indent=2))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog=CLI_COMMAND,
+        description=f"{LANGUAGE_NAME} ({FILE_EXTENSION}) — AI-drawn video language compiler, formatter, validator, and reference renderer.",
+    )
+    p.add_argument("--version", action="version", version=f"{CLI_COMMAND} {PACKAGE_VERSION} (spec {SPEC_VERSION})")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    p_check = sub.add_parser("check", help="Parse and validate a .ncel file with line:column diagnostics.")
+    p_check.add_argument("file", help="Path to .ncel file")
+    p_check.add_argument("--json", action="store_true", help="Output structured JSON diagnostics")
+    p_check.set_defaults(func=cmd_check)
+
+    p_fmt = sub.add_parser("fmt", help="Format a .ncel file into canonical form.")
+    p_fmt.add_argument("file", help="Path to .ncel file")
+    p_fmt.add_argument("-w", "--write", action="store_true", help="Write formatted output in-place")
+    p_fmt.add_argument("--check", action="store_true", help="Exit non-zero if file is not canonically formatted")
+    p_fmt.set_defaults(func=cmd_fmt)
+
+    p_info = sub.add_parser("info", help="Inspect scene/film metadata, layers, rings, and vertex counts.")
+    p_info.add_argument("file", help="Path to .ncel file")
+    p_info.set_defaults(func=cmd_info)
+
+    p_render = sub.add_parser("render", help="Render a single frame of a .ncel scene or film to PNG.")
+    p_render.add_argument("file", help="Path to .ncel file")
+    p_render.add_argument("-o", "--out", help="Output PNG path (default: <file>.png)")
+    p_render.add_argument("-f", "--frame", type=int, default=0, help="Frame index to render (default: 0)")
+    p_render.add_argument("--seed", type=int, default=None, help="Optional seed override")
+    p_render.add_argument("--json", action="store_true", help="Output JSON summary")
+    p_render.set_defaults(func=cmd_render)
+
+    p_film = sub.add_parser("film", help="Render a sequence of frames from a .ncel film to PNGs and optional MP4.")
+    p_film.add_argument("file", help="Path to .ncel file")
+    p_film.add_argument("-o", "--out-dir", required=True, help="Directory for rendered f0000.png frames")
+    p_film.add_argument("--frames", help="Optional frame range '0..5' or comma list '0,1,2'")
+    p_film.add_argument("--mp4", help="Optional output MP4 file path (muxed with ffmpeg if available)")
+    p_film.set_defaults(func=cmd_film)
+
+    return p
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

northcel/config.py

@@ -0,0 +1,12 @@
+"""Single source of truth for NorthCel naming, extension, CLI commands, and version."""
+
+LANGUAGE_NAME = "NorthCel"
+FILE_EXTENSION = ".ncel"
+CLI_COMMAND = "northcel"
+CLI_SHORT_ALIAS = "ncel"
+PYPI_PACKAGE = "northcel"
+NPM_PACKAGE = "northcel"
+PACKAGE_VERSION = "0.1.0"
+SPEC_VERSION = "0.1.0-draft"
+SUPPORTED_SPEC_VERSIONS = ("0.1", "0.1.0", "0.1.0-draft")
+DOCS_URL = "https://northnoir.com/northcel"

northcel/conformance/01_evenodd_aperture.ncel

@@ -0,0 +1,6 @@
+northcel "0.1.0-draft"
+
+scene EvenOddAperture(width: 64, height: 64, fps: 6, precision: 0.25px) {
+  paper { tone: 240, antialias_grid: 4 }
+  layer square_with_hole(tone: 20, rings: 2) { "32,32 192,0 0,192 -192,0|80,80 96,0 0,96 -96,0" }
+}

northcel/conformance/02_color_stroke_ribbon.ncel

@@ -0,0 +1,7 @@
+northcel "0.1.0-draft"
+
+scene ColorStrokeRibbon(width: 64, height: 64, fps: 12, precision: 0.25px) {
+  paper { color: #102030, antialias_grid: 4 }
+  stroke beam(color: #F08040, taper: (8, 4)) { (8, 16), (56, 16) }
+  ribbon wave(color: #40E0D0) { (8, 44, 10), (32, 44, 6), (56, 44, 10) }
+}

northcel/conformance/03_film_def_use_boil.ncel

@@ -0,0 +1,9 @@
+northcel "0.1.0-draft"
+
+film ReusableFilm(width: 64, height: 64, fps: 6, frames: 3, precision: 0.25px, seed: 77) {
+  paper { tone: 235, antialias_grid: 4 }
+  def Box(dx: 0, dy: 0) {
+    layer patch(tone: 30, rings: 1) { "32,32 64,0 0,64 -64,0" }
+  }
+  use Box(dx: lerp(0, 20, t), dy: 0)
+}

northcel/conformance/conformance_manifest.json

@@ -0,0 +1,128 @@
+{
+  "spec_version": "0.1.0-draft",
+  "tolerance_mae": 1.0,
+  "cases": [
+    {
+      "name": "01_evenodd_aperture",
+      "file": "01_evenodd_aperture.ncel",
+      "probes": [
+        {
+          "x": 4,
+          "y": 4,
+          "rgb": [
+            240,
+            240,
+            240
+          ],
+          "note": "outside outer square (paper)"
+        },
+        {
+          "x": 12,
+          "y": 12,
+          "rgb": [
+            20,
+            20,
+            20
+          ],
+          "note": "inside outer square, outside hole (dark)"
+        },
+        {
+          "x": 32,
+          "y": 32,
+          "rgb": [
+            240,
+            240,
+            240
+          ],
+          "note": "inside inner hole (even-odd aperture cutout -> paper)"
+        }
+      ]
+    },
+    {
+      "name": "02_color_stroke_ribbon",
+      "file": "02_color_stroke_ribbon.ncel",
+      "probes": [
+        {
+          "x": 4,
+          "y": 4,
+          "rgb": [
+            16,
+            32,
+            48
+          ],
+          "note": "paper #102030"
+        },
+        {
+          "x": 32,
+          "y": 16,
+          "rgb": [
+            240,
+            128,
+            64
+          ],
+          "note": "center of tapered stroke #F08040"
+        },
+        {
+          "x": 32,
+          "y": 44,
+          "rgb": [
+            64,
+            224,
+            208
+          ],
+          "note": "center of ribbon #40E0D0"
+        }
+      ]
+    },
+    {
+      "name": "03_film_def_use_boil",
+      "file": "03_film_def_use_boil.ncel",
+      "probes_by_frame": {
+        "0": [
+          {
+            "x": 16,
+            "y": 16,
+            "rgb": [
+              30,
+              30,
+              30
+            ],
+            "note": "frame 0 box at x in [8..24]"
+          },
+          {
+            "x": 36,
+            "y": 16,
+            "rgb": [
+              235,
+              235,
+              235
+            ],
+            "note": "frame 0 outside shifted box"
+          }
+        ],
+        "2": [
+          {
+            "x": 16,
+            "y": 16,
+            "rgb": [
+              235,
+              235,
+              235
+            ],
+            "note": "frame 2 box shifted right by +20px"
+          },
+          {
+            "x": 36,
+            "y": 16,
+            "rgb": [
+              30,
+              30,
+              30
+            ],
+            "note": "frame 2 inside shifted box [28..44]"
+          }
+        ]
+      }
+    }
+  ]
+}