4H-Unfolder v0.2.0.A

What's Changed

• docs(wiki): initial wiki draft — user guide + unfold algorithm by @nghiazer in #52
• feat: papercraft-parity Giai đoạn 1 (macOS FlapMerger/offset + cross-platform coplanar-hide) by @nghiazer in #53
• Merge docs/wiki → main: wiki Phase 3 + papercraft-parity Giai đoạn 1 by @nghiazer in #54
• docs: papercraft-parity plan & progress tracker by @nghiazer in #55

Full Changelog: v0.1.1.A...v0.2.0.A

v0.1.1.A - Outline Padding, Merge Adjacent Flaps, Join Connected Cut Edges

What's new in v0.1.1.A

Outline Padding (seam allowance)

Settings -> Print -> Outline padding (mm) -- set any value > 0 to draw a dashed outer guide line around each piece at that offset. Makes cutting easier and ensures pieces fit together. Rendered on the 2-D canvas and embedded in SVG exports.

Merge Adjacent Flaps

Settings -> Print -> Merge adjacent flaps -- when enabled, glue tabs that share a corner vertex on the same piece are combined into a single continuous polygon using Clipper2 boolean union. Eliminates awkward overlapping or gapped tabs at sharp corners.

Join Connected Cut Edges

Right-click any cut edge in the 2-D canvas -> "Join connected cut edges" -- converts the entire chain of adjacent cut edges (connected through shared vertices) to fold edges in one click with full undo support.

---

Bug fixes

• Merged tabs in SVG export were silently truncated to 4 vertices -- now full polygon is preserved
• BorderFoldStyle (fold annotation) was dropped on tab merge -- now propagated from primary tab
• PDO mesh path was missing the Merge Adjacent Flaps step -- now applied consistently
• Fixed duplicate GlueTabGeneratorTests class (CS0101 compile error)

Build

• 95/95 tests pass
• 0 build errors (7 NuGet NU1603 warnings only)
• Clipper2 v2.0.0 (angusj) added as new dependency

Installation

Extract the ZIP and run 4H-Unfolder.exe. No runtime required -- fully self-contained win-x64 binary. All required DLLs are included in the ZIP. Requires Windows 10 / 11 (x64).

v0.0.0.5-alpha — macOS Canvas UX sprint II

macOS — v0.0.0.5-alpha

New features

Multi-select & Group

• Lasso selection — left-drag on empty canvas draws a rubber-band rectangle; all pieces with any vertex inside are selected. Shift+drag = additive.
• Group / Ungroup — select 2+ pieces → Group button assigns a shared userGroupId; grouped pieces move together on drag. Groups are persisted in the .4hu project bundle (userGroups field).
• Right-drag pan — right mouse button drag pans the canvas (replaces the old left-drag-everywhere pan).

Rotate handle

• When 1 piece or 1 group is selected, a ↺ handle appears 44 pt above the centroid with an orange dashed stem.
• Drag the handle to rotate around the effective centroid. Single piece: only pieceRotations updated. Group: all pieces rotate as a rigid body (both pieceRotations and pieceOffsets updated per piece).

Smart join / disjoin

• Disjoin (fold → cut): separated piece is nudged +30 mm right/down so it doesn't overlap the parent, instead of auto-arranging everything.
• Join (cut → fold): click 1 shows a dashed preview arrow between piece centroids (mouse proximity determines anchor/moving direction); any click 2 confirms the join and snaps the merged piece to the anchor's old position.

Bug fixes (since v0.0.0.1-alpha)

• Pieces no longer collapse on first edge/flap click after unfold
• Page grid now expands dynamically when dragging pieces beyond boundaries
• Flap direction corrected (was inward, now outward)
• App no longer auto-unfolds on mesh load

Build info

• Branch: feat/unfold-size-dialog
• Commit: 8f8cb35
• 87 unit tests passing
• macOS 13 Ventura or later required
• Ad-hoc signed — right-click → Open on first launch

Installation

1. Download 4H-Unfolder_v0.0.0.5-alpha_mac.zip
2. Unzip and drag 4H Unfolder.app to Applications
3. First launch: right-click → Open (bypasses Gatekeeper for unsigned builds)

v0.0.0.1-alpha — macOS Alpha

4H-Unfolder v0.0.0.1-alpha — macOS Native

First alpha release of the native macOS Swift port.

Download

File	Platform	Size
4H-Unfolder_v0.0.0.1-alpha_mac.zip	macOS 13+ Ventura or later	~433 KB

Installation: Unzip → Right-click 4H Unfolder.app → Open
(Gatekeeper bypass required once — app is ad-hoc signed, not Developer ID signed)

---

What's in this release

• OBJ (+ MTL textures) and PDO v3 mesh loading
• Kruskal MST unfold → BFS face layout in 2D paper-space
• Interactive 2D canvas — zoom/pan, click edge to toggle fold↔cut, drag piece to reposition
• UV texture rendering — affine-mapped triangles in both 3D (SceneKit/Metal) and 2D canvas
• Glue tabs — Trapezoid / Rectangle / Triangle, 10 FlapMode variants per edge
• Overlap detection — spatial grid + AABB + SAT
• Auto-arrange pieces on paper (A4/A3/A2/A1/Letter/Legal)
• SVG + PDF export
• .4hu project bundle — save/load mesh + overrides + piece positions (cross-platform with Windows)
• Undo/Redo edge and flap overrides
• 4-tab Preferences window (⌘,)
• Drag-and-drop mesh files onto window; file associations for .obj / .pdo / .4hu
• 87 unit tests (XCTest, run in Xcode ⌘U)

Known limitations

• No Developer ID code signing — Gatekeeper bypass required (Right-click → Open)
• SVG/PDF export: solid fill only, no UV texture overlay
• PDO v4 / PD6 format not supported
• Multi-page PDF layout not implemented

Build from source

# Requires Xcode 15+ on macOS 13+
git clone https://github.com/nghiazer/4H-Unfolder.git
cd 4H-Unfolder/4h-unfolder-mac-swift
swift build -c release
# or open Package.swift in Xcode → ⌘R

v0.0.7.B — Toolbar cleanup & reorganization

What's new in v0.0.7.B

Toolbar deduplication & reorganization

Duplicate buttons removed (were showing twice in main toolbar):

• 📐 Unfold
• 💾 Export SVG
• 📑 Export PDF

Icon conflicts fixed:

Old	New	Button
📂	📥	Load Project (was same as Load Mesh)
✂	✄	Edit Flaps (was same as Reset Cutline Edges)
⊞	⤢	Fit Page (was same as Grid Toggle in 2D toolbar)

2D-canvas features moved from main toolbar → 2D toolbar:

• ⬛ Apply Print Transparency
• 🔍 Find Part
• 🗺 / ✕🗺 Insert / Remove Image

---

Installation

Installer — run 4H-Unfolder-v0.0.7.B-setup.exe, requires Windows 10/11 x64, no .NET runtime needed.

Portable — extract 4H-Unfolder-v0.0.7.B-portable.zip, run 4H-Unfolder.exe. Keep all DLLs in the same folder.

v0.0.5.A — Edit Flaps (per-edge glue tab placement)

What's new in v0.0.5.A

✂ Edit Flaps dialog — Pepakura-style per-edge glue tab control

A new modeless Edit Flaps dialog (✂ toolbar button) gives fine-grained control over glue tab placement on every edge.

Shape(S) tab — override tab height/angle globally via [to all]

Position(Q) tab — click any edge in the 2-D canvas to apply:

Inner edge mode	Effect
Switch Flap Position	Move tab to opposite face
ON-ON (This Side)	Force tab on clicked face
OFF-ON (Other Side)	Force tab on partner face
OFF-OFF (No Flap)	Remove tab from this edge
ON-ON (Both Sides)	Tabs on both faces
Do Nothing	Restore default

Border edge mode	Effect
Do Nothing	No tab (default)
Flap with Mountain Fold	Border tab + mountain fold
Flap with Valley Fold	Border tab + valley fold
Flap without Fold	Border tab, no fold line
No Flap	Explicit no-tab

Overrides persist in .4hu bundles and are fully undo/redo-able.

UI fixes

• Unfold button icon ⚙ → 📐 (distinct from Settings ⚙)
• App now starts maximized

---

Installation — portable (no install required)

Download all 7 files below into the same folder and run 4H-Unfolder.exe.

⚠ All DLLs are required — the exe will not start without them.

Requirements: Windows 10/11 x64. No .NET runtime needed (self-contained).

v0.0.4.F — Assembly Animation: 3-phase lift-off + fold + fly toward camera

Assembly Animation — Complete 3-Phase Overhaul

This release brings a fully polished step-by-step assembly animation with three distinct visual phases per step:

Phase 0 — Lift-off from 2D canvas

Each piece starts flat at its exact 2D canvas layout position, then arcs upward via a smooth sin-curve before settling at the fold origin. The opening frame mirrors the 2D layout canvas exactly.

Phase 1 — Paper-fold

Faces rotate around shared fold edges using BFS spanning tree + accumulated Matrix4x4 transforms — true paper-folding simulation.

Phase 2 — Fly toward camera (new in F)

The folded shape translates and scales upward to a staged model position directly above the canvas. Pieces visually grow as they rise (stageScale ≥ 1.2×), giving a clear "flying toward the viewer" effect.

Scene & Camera

• Unified viewport: 2D canvas plane at bottom, assembled model at top
• Faint amber ghost of the fully assembled model always visible as destination hint
• Camera auto-positions on open to frame both planes simultaneously (30°/45° perspective)

Bug fix

• ToFlatV scale bug fixed: canvas/fold positions now correctly match 3D mesh scale for non-PDO formats (OBJ, FBX, etc.)

---

Download

Package	Platform
4H-Unfolder-v0.0.4.F-setup.exe	Windows 10/11 x64 installer (recommended)
4H-Unfolder-v0.0.4.F-portable.zip	Portable — extract and run, no install needed

No runtime required — fully self-contained win-x64 binary.

v0.0.4.C - Dialog UX overhaul x3

Dialog UX overhaul: toolbar icon fix + ModelOrientation layout + UnfoldSetup 2-col grid + AssemblyAnimation step slider + clean viewport. Bug fix: _suppressStepRefresh.

v0.0.3.H - Performance + 2D Canvas UX

What's new in v0.0.3.H

Performance

• OverlapDetector spatial grid — replaced O(n²) AABB nested loop with uniform bucket-partition broad phase. Each face is placed in all grid cells its AABB covers (typically 1-4 cells); only pairs sharing a cell are tested. Cell size = max(2 x avg AABB side, canvas extent / 256) keeping the grid at most 256x256. On spread-out n=2000 meshes: ~4 000 comparisons vs 2 000 000 (~500x speedup). Candidate pairs deduplicated with HashSet; correctness guaranteed - overlapping AABBs always share at least 1 cell.

2D Canvas UX

• Uniform 2D view background — removed the inner canvas rectangle boundary. The ScrollViewer now receives CanvasBackground from settings; RootCanvas is transparent. The entire 2D window shows one seamless color. Theme fallback values synced. Settings label renamed to "2D view background".

Other

• All 56 tests pass
• Installer: 4H-Unfolder-v0.0.3.H-setup.exe (Inno Setup, win-x64, ~48 MB)
• Portable: 4H-Unfolder-v0.0.3.H-portable.zip (~66 MB)

---

Installation

Run the installer (-setup.exe) or extract the portable ZIP anywhere and run 4H-Unfolder.exe. No .NET runtime required — fully self-contained win-x64.

v0.0.3.C - PDO pieces no longer disappear on first click

v0.0.3.C - PDO pieces no longer disappear on first click

Bug fix

• BUG-PDO-3: RunAutoArrange sign error in rot=90 branch caused PDO pieces to be placed at negative canvas_X. Fixed formula: localX + minY + hNat.
• Defensive: ScrollToShowPiece scrolls 2D viewport to any newly selected piece if outside the visible area.

Open source

This project is now published under the MIT License.

• License: https://github.com/nghiazer/4H-Unfolder/blob/main/LICENSE
• Contribution guide: https://github.com/nghiazer/4H-Unfolder/blob/main/CONTRIBUTING.md

Download

Extract the ZIP, then run Install.ps1 (admin = system-wide, non-admin = user-only) or run the EXE directly.

Requirements

• Windows 10 / 11
• No .NET runtime required (self-contained)

Tests

56 / 56 unit tests passing.