Natelier

Natelier is a high-performance, parametric 3D modeling and rendering engine designed for cross-platform applications, including mobile devices (Android and iOS), desktop environments, tablets, and flat-screen VR interfaces. Built using Python, Kivy, and NumPy, the application provides an interactive 3D modeling workspace driven by a custom mathematical expression engine and dependency graph resolution.

---

Technical Architecture and System Design

Parametric Vertex System

The modeling pipeline is built around an atomic vertex system that supports both static coordinates and dynamic parametric evaluation:

• Base Points: Atomic units defined by a unique string identifier and $(x, y, z)$ floating-point coordinates. Semantic identifiers (e.g., face_left_cheek_3) allow for structured mapping.
• Point Groups: A hierarchical tree structure that supports grouping points or other groups. Colors assigned to groups propagate through the hierarchy:
  • The broadest parent group's color determines the point outline color.
  • The deepest nested group's color determines the point fill color.
  • If only one group defines a color, it is applied to both the outline and fill.
  • Unassociated points fall back to default styling.

Variable System

To facilitate dynamic parametric adjustments, the application implements two classes of variables:

• Slider Variables: Floating-point parameters configurable within the user interface via range sliders, defining value, min, max, and step values.

• Macro Variables: Dynamic equations mapping relationships between multiple variables, automatically re-evaluated when dependent variables change. For example:

  $$c = \text{MacroVar}(\text{expression} = \text{"sqrt((a - b) ** 2)"})$$

Dynamic Parametric Points

Users can define point coordinates using algebraic and geometric expressions that reference other points and variables:

$$p_3 = p_1 \cdot a + p_2 \cdot (1 - a)$$

These positions are computed dynamically. To ensure mathematical consistency:

• The system constructs an expression dependency graph on modification.
• A cycle-detection algorithm validates changes, preventing dependency loops.

---

Core Primitives and Rendering

Triangles

Triangles form the renderable primitives of the 3D engine. Points are rendered in the modeling editor, whereas triangles represent the solid geometry of the scene:

{
  "triangle_id": {
    "points": ["p1", "p2", "p3"],
    "color": [255, 255, 255],
    "texture_id": null,
    "texture_mapping": [
      [0.0, 0.0],
      [0.0, 1.0],
      [1.0, 1.0]
    ]
  }
}

Texture Mapping (UV Layout)

The engine supports mapping 2D image textures to 3D triangles. The application includes a visual UV editor canvas allowing users to map coordinate textures directly to triangular faces, independent of the 3D vertex positions.

---

Computational Mechanics

Expression Parsing and Dependency Graphs

Mathematical expressions for macro variables and parametric points are parsed into a custom expression tree structure (ExpressionGraph). An input expression such as p1 * a + p2 * (a - 1) compiles to: ExpSum(ExpProd(ExpPoint("p1"), ExpVar("a")), ExpProd(ExpPoint("p2"), ExpSub(ExpVar("a"), ExpConstant(1))))

To optimize performance:

• The engine evaluates operations using vectorized NumPy arrays.
• A dirty propagation system (is_dirty flag) ensures only affected branches are recalculated.
• A lookup table registers point and variable expression references, updating only the dependents of modified elements.

Action Stack (Undo/Redo)

State modifications are managed via an command pattern interface. The application features an undoable action stack where operations inherit from an abstract Action class implementing do() and undo() methods.

---

User Interface Design

The application features a responsive dual-panel layout, adapting to screen ratios (dual-column for landscape, dual-row for portrait).

Viewport Panel

• 3D Renderer (Base Layer): Renders the active 3D geometry, wireframes, and shading.
• Control Overlay (Top Layer):
  • Tool Palette: Switch between View (camera orbit), Move Point (coplanar projection translation), Scale (selection scaling), and Rotate (selection rotation around center of mass).
  • Visualization Toggles: Wireframe mode, solid mode (flat shading, no textures), and triangle-only visualization.
  • Snap-to-Grid: Anchor points to a configurable grid.
  • 3D Space Gizmo: Visual guide showing camera orientation.

Tools & Control Panel

A tabbed interface organizes the editor controls:

• Points: Creation and modification of points, grouping controls, coordinate inputs, and a searchable tree view of scene elements.
• Groups: Property editor for hierarchical collections, color picking, and selection utilities.
• Triangles: Geometry construction from selected vertices, color controls, and texture assignment.
• Texture Mapping: Visual UV coordinate workspace.
• Textures: Asset management tool to import, rename, and delete texture images.
• Camera: Transform input parameters (position, rotation, FOV) and viewport reset controls.
• Actions: Command execution history and undo/redo operations.
• Settings: Global application presets and system configurations.
• Project: File lifecycle controls (New, Open, Save, Save As).

Viewport Division Handle

A floating partition widget allows swapping panel positions and toggling fullscreen view mode.

---

Project Structure

Natelier/
├── buildozer.spec            # Android build configuration
├── natelier.spec             # PyInstaller package specification
├── pyproject.toml            # Linter and type checker configurations
├── requirements.txt          # Production application dependencies
├── requirements_dev.txt      # Development dependencies
├── src/                      # Source directory
│   ├── main.py               # Main application entry point
│   ├── config.py             # Global configurations
│   ├── app/                  # Application and UI layer
│   │   ├── app.py            # Kivy application wrapper
│   │   ├── settings_storage.py  # User settings serialization
│   │   ├── panels/           # Layout and workspace panels
│   │   ├── screens/          # Main application screens (Home, Project)
│   │   └── tabs/             # Control panel tabs
│   ├── core/                 # Core engine logic
│   │   ├── scene.py          # Global scene state model
│   │   ├── serialization.py  # JSON project state serializer
│   │   ├── models/           # Data models (Points, Groups, Triangles, Variables)
│   │   └── expressions/      # Custom math parser and evaluation graph
│   └── renderer/             # 3D renderer pipeline
│       ├── camera.py         # Perspective/Orthographic camera transformations
│       ├── chunk_manager.py  # Dynamic rendering optimizations
│       └── layers/           # Scene render layers
└── tests/                    # Test suite
    ├── core/                 # Core logic unit tests
    └── renderer/             # Renderer unit tests

---

Installation & Setup

Prerequisites

• Python 3.10 or higher
• Development libraries for Kivy dependencies (platform-dependent)

Environment Configuration

1. Clone the repository:

   git clone https://github.com/nath54/Natelier.git
   cd Natelier

2. Create and activate a virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install project dependencies:

   pip install -r requirements.txt

4. Install development dependencies:

   pip install -r requirements_dev.txt

Execution

Run the application using the entry script:

python -m src.main

Running Tests

Execute the unit test suite using pytest:

pytest

---

Building for Android

The project compiles to Android packages using Buildozer.

1. Ensure target dependencies (Java Development Kit, Android SDK/NDK, and basic build tools) are configured.
2. Compile and package the application:

   buildozer android debug deploy run