Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/toledoem/stlshaper

Real-time STL deformation tool. Apply noise, sine wave, and pixelate effects to 3D models using p5.js & Three.js. Create unusual and captivating visuals – a playground for generative art
https://github.com/toledoem/stlshaper

3d-printing algorithmic-art design-systems generative-art p5js parametric-modeling stl threejs visualisation

Last synced: 21 days ago
JSON representation

Real-time STL deformation tool. Apply noise, sine wave, and pixelate effects to 3D models using p5.js & Three.js. Create unusual and captivating visuals – a playground for generative art

Awesome Lists containing this project

README 

          
# STLShaper ~ Subversion of Form

Version: 0.7.0 (2026-04-21)



**This is under constant development and may change at any time :-)** 



STLShaper loads STL files and applies mathematical deformations: noise, sine waves, pixelation, IDW control points, and topology-altering methods. You adjust parameters and export the result. The point is to make your models deliberately weird—unsettling, beautiful, broken.



## Motivation & Creative Exploration



- Subversion of Form: This project isn’t about perfect realism. It's about deliberately distorting the familiar, creating unsettling or intriguing shapes.

- Algorithmic Abstraction: Noise, sine waves, and inverse distance weighting deform geometry in predictable and chaotic ways.

- Visual Metaphors: Consider how different deformations might represent abstract concepts – chaos, tension, growth, decay, organic transformation.





  STLShaper Demo




## Features



- **STL Loading**: Loads STL files using the Three.js STLLoader. (Start with simple objects – boxes, spheres, basic shapes – to get the basics working).

- **Deformation Effects**:

  - **Noise**: Applies a noise-based deformation, introducing chaotic movement and distortion.

  - **Sine Wave**: Displaces vertices along a sine curve, creating rhythmic ripples across the model.

  - **Pixelate**: Pixelates the model by snapping vertices to a grid, offering a stark, fragmented aesthetic.

  - **IDW Shepard**: Multiple control points scattered through the model's interior. Each vertex moves based on distance to those points—closer points pull harder.

  - **Inflate / Twist / Bend / Ripple / Warp / Hyperbolic Stretch**: A suite of expressive surface operators. Inflate swells outward by distance from center, Twist rotates along a chosen axis, Bend arcs the mesh over a controllable range, Ripple adds wave-like undulation, Warp introduces spatial noise-based offsets, and Hyperbolic Stretch exaggerates form along an axis for elastic, pulled silhouettes.

  - **Tessellate / Boundary Disruption / Menger Sponge**: Topology-oriented transformations. Tessellate subdivides triangles to add geometric density, Boundary Disruption jitters near edges for torn or frayed contours, and Menger Sponge carves repeating voids for porous, lattice-like structures.

  - **Perspective Distortion**: Directional fisheye/barrel distortion controlled by an interactive circle widget. Drag the dot toward any direction to stretch vertices that way; center dot = no effect. Supports 1-point and 2-point vanishing modes, plane selector (XY/XZ/YZ), strength slider, and linear or exponential falloff.

- **Real-time Deformation**: Updates the deformation in real-time, allowing for interactive experimentation.

- **Parameter Controls**: Interactive sliders and checkboxes for adjusting deformation parameters.

- **Adaptive Parameter Ranges**: Parameters automatically scale based on model size to ensure consistent effects across different STL scales.

- **Visual Feedback**: Displays the deformed model in 3D space with control point visualization for IDW deformation.

- **Parallel Processing**: Uses Web Workers for efficient processing of large STL files with thousands of vertices.

- **Preprocess Options**: Optional cleanup before deformation. Decimate keeps a percentage of triangles (faster but less detail), and Vertex Merge collapses near-identical vertices within an epsilon (reduces duplicates and can stabilize deformations). Not required for most models, but helpful for very dense STLs or when you need faster iteration.

- **Stats HUD**: Displays vertex/triangle counts and deformation time.

- **Export**: Exports the deformed model as an STL file – save your weird creations!



## Deformation Examples





  Original STL Model

  
Original STL Model in STLShaper






  Noise Deformation

  
Noise Deformation in STLShaper






  Sine Wave Deformation

  
Sine Wave Deformation in STLShaper






  Pixelated Deformation

  
Pixelated Deformation in STLShaper






  Bend Deformation

  
Bend Deformation in STLShaper






  Ripple Deformation

  
Ripple Deformation in STLShaper






  Hyperbolic Stretch Deformation

  
Hyperbolic Stretch Deformation in STLShaper




## IDW Shepard Deformation



Control points pull vertices based on distance. Closer points pull harder. The result: smooth, organic bending without the grid-like feel of axis-based or noise-driven methods.



### Key Features:

- **Poisson Disk Sampling**: Control points are distributed using Poisson disk sampling to ensure even coverage and prevent clustering

- **Volume-Constrained Placement**: All control points are guaranteed to be inside the mesh volume, not just within the bounding box

- **Seed-Based Generation**: Deterministic point placement using a numeric seed for reproducible results

- **Manual Control Points**: Optional manual list of control points (supports single-point or multi-point inputs)

- **Sampling Rays Control**: Adjust inside-mesh sampling rays to balance speed and robustness

- **Adaptive Influence**: Each control point exerts influence based on inverse distance weighting with customizable power falloff

- **Visual Feedback**: Red wireframe spheres show the location and influence areas of all control points

- **Scalable Effects**: Parameter ranges automatically adjust based on model size to prevent over/under-deformation



### Technical Implementation:

- **Multi-Point IDW**: Each vertex is influenced by all control points simultaneously

- **Parallel Processing**: Web Workers handle the computational load for large models

- **Real-time Visualization**: Control points scale with model size (5% of largest dimension)

- **Robust Volume Detection**: Advanced ray casting ensures points are truly inside the mesh

## Requirements



*   **Web Browser:**  A modern web browser with Web Worker support (Chrome 4+, Firefox 3.5+, Safari 4+, Edge)

*   **JavaScript:**  ES6+ features supported by your browser

*   **Three.js:** r121 (bundled).  This project uses Three.js for 3D rendering and ray casting.

*   **FileSaver.js:** (Included) For exporting the STL file.

*   **Web Workers:** Required for parallel processing of large deformations, especially IDW with multiple control points.



## Run Options



You can use STLShaper in either of these ways:



1. **Run locally:** Clone this repository and open `index.html` in a modern browser.

2. **Run online:** Open the hosted version directly at [https://toledoem.github.io/stlshaper/](https://toledoem.github.io/stlshaper/).



## Setup



1.  **Files:**  The project consists of `index.html`, `sketch.js`, and the required JavaScript libraries.

2.  **Import:**  Place all files in a directory.

3.  **Run:**  Open `index.html` in your web browser.



## Usage



1.  **Load STL:**  Click the "File Input" button to select an STL file.

2.  **Deformation Type:** Choose the deformation type from the radio buttons (Noise, Sine Wave, Pixelate, IDW Shepard).

3.  **Adjust Parameters:** Use the sliders and inputs to control the deformation parameters. IDW parameters adapt automatically to model size.

4.  **Generate Deformation:** Click the "Generate Deformation" button.

5.  **Visualize:** The deformed model will be displayed in the 3D view. For IDW, red spheres show control point locations.

6.  **Export (Optional):**  Click the "Export Current STL" button to save the deformed model as an STL file.



## Controls



*   **File Input:** Select an STL file.

*   **Radio Buttons:** Choose the deformation effect (Noise, Sine Wave, Pixelate, IDW Shepard).

*   **Sliders:** Adjust the parameters of the chosen effect.



### Noise Controls:

*   **Intensity:** Controls the strength of the noise deformation (0.1 - 5.0)

*   **Scale:** Controls the frequency/size of noise features (0.005 - 0.5)

*   **Axis:** Choose which axes to apply noise to (All, X, Y, Z, or combinations)



### Sine Wave Controls:

*   **Amplitude:** Controls the height of the sine waves (1 - 100)

*   **Frequency:** Controls how many waves fit in the model (0.01 - 0.2)

*   **Driver Axis:** Which axis provides the input to the sine function (X, Y, Z)

*   **Displacement Axis:** Which axes the sine wave displaces (X, Y, Z, or combinations)



### Pixelate Controls:

*   **Voxel Size:** Size of the pixelation grid (0.5 - 50)

*   **Axis Lock:** Which axes to pixelate (All, X, Y, Z, or combinations)



### IDW Shepard Controls:

*   **Number of Points:** How many control points to generate (3 - 50). More points = more complex deformation.

*   **Seed:** Numeric seed for reproducible control point placement (0 - 10000). Change for different distributions.

*   **Weight:** Strength of attraction/repulsion at control points (± adaptive range based on model size)

*   **Power:** How quickly influence falls off with distance (0.5 - 6.0). Higher = more localized effects.

*   **Global Scale:** Overall scaling factor for the deformation (adaptive range based on model size)



*   **Generate Deformation:** Apply the deformation.

*   **Export Current STL:** Export the deformed model.



## Code Structure



*   **`index.html`:**  The main HTML file that sets up the Three.js scene, UI elements, and event listeners.

*   **`main.js`:**  Contains the core logic for loading the STL, applying the deformation, rendering the model, and handling user interactions. Includes Poisson disk sampling, volume detection, and adaptive parameter scaling.

*   **`worker.js`:** Web Worker for parallel processing of vertex deformations, especially important for IDW with multiple control points.

*   **`libraries/`:** Contains Three.js, p5.js, and other required libraries.



## Performance & Technical Notes



*   **Parallel Processing:** Uses Web Workers to distribute deformation calculations across CPU cores, enabling real-time processing of large STL files.

*   **Adaptive Parameters:** IDW parameters automatically scale based on model dimensions to ensure consistent deformation strength across different model sizes.

*   **Volume Sampling:** Advanced ray casting ensures IDW control points are placed inside the mesh volume for maximum effect.

*   **Memory Management:** Efficient cleanup of 3D objects and Web Worker communication for stable performance.

*   **Model Size Handling:** The system gracefully handles models from small prototypes to large architectural scans.



## Notes



*   Performance depends on model complexity and chosen algorithm.

*   Rendering can be slow with dense meshes.

*   After deformation, you may need to repair the mesh in Meshlab: Filters → Cleaning and Repairing → Remove Zero Area Faces, Repair Non-manifold Edges.

*   IDW Shepard deformation works best with solid, manifold meshes. Complex or thin-walled models may produce unexpected results.



## License & Attributions



**STLShaper** is released under the [MIT License](LICENSE).



For a detailed breakdown of third-party libraries and attributions, see the [License & Attributions](https://toledoem.github.io/stlshaper/documentation.html#license--attributions) section in the full documentation.



### Quick Reference



- **Three.js** (v0.121.1) – [MIT License](https://github.com/mrdoob/three.js/blob/master/LICENSE)

- **Bootstrap Icons** – [MIT License](https://github.com/twbs/icons/blob/HEAD/LICENSE)

- **FileSaver.js** – [MIT License](https://github.com/eligrey/FileSaver.js/blob/master/LICENSE.md)

- **NIH 3D Print Exchange** – [Public Domain](https://3dprint.nih.gov/)



Built by **Enrique Toledo** ([@ToledoEM](https://toledoem.github.io/))



---



**Disclaimer:** This tool is provided as-is for experimental and educational purposes. The deformations applied are artistic and mathematical in nature and may not preserve properties required for 3D printing or clinical use. Always validate exported models for your specific use case.