How origamimagiro/flat-folder works
Project Type & Purpose
• Flat-Folder is a full-stack web application (client-side heavy) primarily built in JavaScript. Its purpose is to import crease pattern files, compute folding states (using Boolean variables and constraint graphs for overlapped crease faces), and display the results visually in the browser.
• The README details both the user interface flow (input file, crease pattern drawing, overlap graph, flat folded state, and export options) and the algorithmic details (computation of overlapping relationships, constraint propagation, and state enumeration).
Main Architectural Components
a. Presentation (UI) Layer:
• HTML/CSS/JS front end structure:
• index.html and batch.html serve as entry points.
• The GUI is handled by src/gui.js, which works together with the image assets (in the img folder) and uses SVG rendering (src/svg.js) to present the crease pattern and folded/overlap graph views.
• User Interaction:
• UI elements for file uploading, “Fold”, “Flip”, and “Export” options.
• Visualization of computed states (highlighted faces, overlays, text labels) and interactive components (e.g., clicking on a cell or face to display constraints).
b. Core Engine / Business Logic:
• Input/Output and File Handling:
• src/io.js manages file imports, parsing crease pattern formats.
• src/conversion.js converts data between FOLD, SVG, OPX, and CP formats.
• Computational Modules:
• src/compute.js and src/solver.js house the algorithms to compute valid fold states.
• src/constraints.js encapsulates computation of the four types of constraints (taco-taco, taco-tortilla, tortilla-tortilla, and transitivity) and manages Boolean variable assignments.
• src/math.js provides necessary mathematical operations used across the algorithm (for single-precision handling, distances, angles, etc.).
• src/note.js may be used for logging or debugging specific details in the folding process.
• src/examples.js assists with managing the examples available in the “examples” directory.
c. Parallel / Asynchronous Processing:
• Web Worker Integration:
• src/worker.js and modules in src/node_Worker_polyfill handle the heavy, asynchronous computation of the constraint graph and variable assignments.
• src/parallel.js coordinates dispatching work to these workers to avoid UI blocking during intensive computations.
• Flow: the UI invokes a computation → manager module dispatches work to a Web Worker → worker computes parts (constraint satisfaction, solution search) and returns results.
d. Data & Examples:
• Examples Folder:
• The “examples” directory contains numerous crease pattern files (*.fold) and CSV data files used for demonstration or testing.
• This folder’s content ties into the input modules and illustrates the variety of use cases.
• Export & Logging:
• The system supports export options (using src/svg.js to export snapshots, and “log” functionality to output console output).
Module Relationships and Data Flow
• Then, pass the parsed file to src/conversion.js to transform it into an internal data structure.
• This internal representation is handed to the Core Engine modules (src/compute.js, src/solver.js, src/constraints.js) which represent the computational “heart” of the application.
• That these modules use mathematical utilities (src/math.js) and delegate heavy tasks to asynchronous workers (src/worker.js via src/parallel.js).
• Once computations are finished, data is passed back to the GUI (src/gui.js) and the SVG renderer (src/svg.js) for display.
• The system also interacts with the “examples” data repository when a user wishes to load sample crease patterns.
Architectural Patterns and Design Principles
• Modular Design: Each functionality (I/O, Conversion, Computation, Parallel Processing, GUI) is encapsulated in its own JS module.
• Separation of Concerns: UI responsibilities are kept separate from the computational logic and data processing.
• Asynchronous Processing: Heavy computation is offloaded to Web Workers, ensuring the web interface remains responsive.
• Data Flow is clearly unidirectional: Input → Transformation → Computation → Rendering, with paths for exports and logging.