Skip to content

docs: align apply-template guides with deferred-rounding pipeline#4

Open
giardiello wants to merge 1 commit into
base/adam-ef57e1f6from
docs/apply-template-rounding-update
Open

docs: align apply-template guides with deferred-rounding pipeline#4
giardiello wants to merge 1 commit into
base/adam-ef57e1f6from
docs/apply-template-rounding-update

Conversation

@giardiello

Copy link
Copy Markdown
Owner

Summary

Both implementer-facing docs (FDL_Apply_Template_Logic.md and FDL_Template_Implementer_Guide.md) were still describing the old "round everything to integers after scaling" behaviour. The pipeline has been reshaped around Adam's `ef57e1f6` rounding work:

  • Rounding is deferred to the end of the pipeline (new Phase 9b, after crop), not applied mid-pipeline after scaling.
  • Only canvas.dimensions and canvas.effective_dimensions are integerized. protection_dimensions, framing dimensions, and all anchors stay float per the "fractional pixels" model.
  • effective_dims is always ceil'd -- the template's RoundStrategy only applies to canvas.dimensions.
  • Rounding deltas are absorbed symmetrically into anchor positions (delta/2) so content stays centered on its pre-round center across chained template applications.
  • _scaled_bounding_box and _content_translation are exported as custom attributes in their pre-round float form, so image processors (e.g. `fdl_imaging`'s warp-based pipeline) can place content at sub-pixel precision without re-quantizing.

This PR is docs-only -- no code changes. It brings both guides in sync with the current `native/core` code at `ef57e1f6`.

Changes

`FDL_Apply_Template_Logic.md`

  • Pipeline ASCII diagram updated ("5. Scale (float)" + new "9b. Round & Absorb").
  • Step 5 rewritten -- rounding language removed.
  • New Step 9b with the full `geometry_round()` algorithm (ceil effective, round canvas, clamp inner, symmetric anchor shift, per-axis dim shrink, hierarchy re-establishment).
  • Step 10 custom-attributes description clarified as pre-round float.
  • "Complete Formula Reference" header now says inputs are floats.

`FDL_Template_Implementer_Guide.md`

  • Section 2.1 ops table: `fdl_geometry_round()` description updated.
  • Section 4.5 rewritten for the no-rounding Phase 5 semantics.
  • New section 4.9 "Phase 9b: Round Integer-Typed Schema Fields" with pseudocode mirroring `geometry_round()`.
  • Section 5.6 retitled "Exact Float Comparison in FIT Regime" -- explains why FIT detection stays bit-exact despite Phase 5 no longer rounding.
  • Section 6.1 output-object fields annotated with float/integer status.
  • Section 7 formula inputs annotated as floats.
  • Section 8 summary table: phase 5 renamed, phase 9b added; "Round early" design decision replaced with "Round late, absorb into anchors"; added a 7th decision about the unrounded side-channel for imaging.

`docs/svg/02_pipeline_overview.svg`

  • Phase 5 label updated.
  • New Phase 9b box inserted between Phase 8 and the (now Phase 10) output step; viewBox and background extended by 76px to fit.

Test plan

Docs-only change -- no tests affected. Verification:

  • Reviewer confirms the Phase 9b algorithm in both docs matches the actual C++ in `native/core/src/fdl_geometry.cpp::geometry_round()` at `ef57e1f6`.
  • Reviewer confirms the custom-attribute descriptions (`_scaled_bounding_box`, `_content_translation` as pre-round floats) match what is actually written in `fdl_template.cpp::build_template_output_document()`.
  • Visual sanity check of the updated `02_pipeline_overview.svg` (the `.png` sibling is stale and will need regeneration from whatever tool originally produced it).

Base

Based on `base/adam-ef57e1f6`. The docs on that base are identical to those on `origin/dev`, so this change can be re-targeted to `origin/dev` once Adam's rounding work lands upstream.

Made with Cursor

The template pipeline no longer rounds during Phase 5 -- rounding has
been consolidated into a single late pass (Phase 9b) after crop, and
the rounding model itself has changed.  The docs were still describing
the old "round everything to integers after scaling" behaviour.  This
brings both implementer-facing guides in sync with the current code
(native/core/src/fdl_template.cpp + fdl_geometry.cpp).

Changes
-------

FDL_Apply_Template_Logic.md
  - Pipeline ASCII diagram: replace "5. Scale & Round" with
    "5. Scale (float)" and add "9b. Round & Absorb" before step 10.
  - Step 5 renamed to "Scale (no rounding)"; rounding language removed;
    note that scaled_bounding_box is captured pre-round as a float and
    stored on the output as _scaled_bounding_box.
  - New Step 9b "Round Integer-Typed Schema Fields" with the full
    algorithm:
      * canvas rounded per RoundStrategy; effective always ceil'd
      * protection / framing / all anchors stay float
      * ceil delta absorbed into effective_anchor as -delta/2
      * canvas delta shifted symmetrically (+delta/2) into all anchors
      * per-axis clamp: preserve inner anchors, shrink dims; for
        effective use floor(canvas-anchor) to keep the integer invariant
      * hierarchy re-established after the floor step
  - Step 10 custom-attributes description updated: _scaled_bounding_box
    and _content_translation are unrounded floats by design; may differ
    by sub-pixel amounts from the rounded canvas.dimensions.
  - "Complete Formula Reference" header updated: inputs are floats,
    integerization happens later.

FDL_Template_Implementer_Guide.md
  - Section 2.1 ops table: fdl_geometry_round() description updated.
  - Section 4.5 rewritten for the no-rounding Phase 5 semantics.
  - New section 4.9 "Phase 9b: Round Integer-Typed Schema Fields" with
    pseudocode mirroring geometry_round() in the core.
  - Section 5.6 "Exact Integer Comparison" renamed to "Exact Float
    Comparison"; explains why FIT detection stays bit-exact despite
    Phase 5 no longer rounding.
  - Section 6.1: canvas/effective annotated as integer "after Phase 9b";
    inner dims and anchors annotated as float; custom-attributes table
    clarifies that _scaled_bounding_box and _content_translation are
    post-scale, pre-round.
  - Section 7 formula: inputs annotated as floats.
  - Section 8 summary table: phase 5 renamed, phase 9b added; "Round
    early" design decision replaced with "Round late, absorb into
    anchors"; "Exact integer comparison" restated as exact FIT detection
    via variable identity; added a 7th decision about the unrounded
    side-channel for imaging.

svg/02_pipeline_overview.svg
  - Phase 5 label updated.
  - New Phase 9b box inserted between Phase 8 and the (now Phase 10)
    output step; viewBox and background extended by 76px to fit.

No code changes.  Both guides now match Adam's ef57e1f rounding
pipeline and the fractional-pixels model downstream consumers rely on.

Made-with: Cursor
@giardiello giardiello requested a review from davisadam10 as a code owner April 25, 2026 19:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant