Abundance

Abundance

🌐 Live Application: abundance.maslowcnc.com

• Getting Started
  • Login with GitHub
  • Projects Screen
• Create Mode - Making Your First Project
  • Layout of the program
  • Flow
  • Atom Menu
  • Connectors
• 3D Viewer
  • Output
• Onwards to a simple box!
  • Boolean Operations
  • Move
  • Inputs and Equations
  • Github Molecules
  • Exports
• Run Mode
• Working with an AI Agent
• Atoms Reference
• Contribute

Getting Started

Abundance breaks with the tradition of CAD programs which inherit from drawing programs and instead inherits from logical languages like programming. This allows it to be a CAD program which can have language-like features such as importing modules, version control, and collaboration. All projects are stored as GitHub repositories, enabling seamless version control and collaborative design workflows.

Login with GitHub

You can view other's projects, change their parameters, and export their outputs (eg: STL, gcode) without logging in.

To make your own projects log in with a GitHub account. GitHub accounts are free to create, if you already have a GitHub account you may use it or create a new one. Each project you create in Abundance will be stored as a Github Repository. You can always search for them and find them through the Abundance Platform.

Projects Screen

Choose whether you want to create a new project, go into one of your existing projects, or take a look at a project that someone else created. If you own the selected project, you will be redirected to Create Mode. If the project belongs to someone else, you will be redirected to Run Mode where you can choose to fork the project to modify it or simply download it.

Create Mode - Making Your First Project

Layout of the program

Create Mode is the primary workspace for making new projects. It has two areas. On top is the logical flow of the design. On bottom a 3D view of your model appears.

Flow

A model within Abundance is composed of interconnected nodes called Atoms and Molecules, linked by connectors. An atom is a shape or an operation you can perform on a shape (ie circle or translate). A molecule can contain any number of atoms in a configuration (ie generate a table leg).

Most Atoms and molecules have inputs. Eg: the Circle atom has a diameter input. You can type in the desired diameter, or link a connector to that input, eg: from an equation or user input.

If you have a background in programming, think of Atoms as the built-in language functions and molecules as the functions you create.

Atom Menu

To see and place the available atoms on your flow screen start by right-clicking anywhere within the flow screen area to spawn the circular atom menu. Move your cursor around to spawn the sub-menus and click on the atom you want to place.

As an example, add a rectangle atom, found in the right sub-menu. Enter a desired width and length, say 10 by 15. By default new shapes appear at the origin on the XY plane

Connectors

Atoms can be connected by click-and-drag from the output (right) connector of one atom to the input of another atom.

As an example, add an extrude atom then connect from the rectangle output to the geometry input on the extrude atom. Notice, extrude also has an input for extrusion height.

3D Viewer

The 3D view on the bottom of the page shows the currently selected atom. Click on atoms on the page to view the geometry at that point in the project.

Output

Link an atom to the Output on the right side of the flow to make that atom the final step in your project.

By default the output of your project will be shown in the 3D view whenever no other atom is selected and will be shown as a translucent backdrop to all other atoms.

Onwards to a simple box!

Here we'll highlight some common functions as we design a simple box project.

Boolean Operations

Boolean operations let existing shapes affect one another. There are three Boolean Operations in Abundance, all in the bottom right menu:

1. Difference - remove all overlaps between parts
2. Fuse - join together both parts
3. Intersect - keep only the overlapped area of the parts

To cut out the middle of our box we'll use a boolean difference.

1. Copy paste the existing rectangle and extrude. Ctrl+click to select both atoms. Ctrl+C, Ctrl+V to copy and paste them.
2. Update the dimensions of the new rectangle to be a little bit smaller than before.
3. Add a difference atom. Connect our first rectangle to "retain" and the new one to "remove"
4. Link the output of the difference atom to the Output atom on the right side of the flow panel.

Move

Our box now has no base. To fix this we need to shift our "remove" box upwards.

Add a move atom from the bottom left menu to the canvas. Connect the smaller rectangle to it's "geometry" input. Set a small positive value on the "z" input.

Drag a connector from move's output to the "remove" input on the difference atom. Making this connection will automatically replace the prior connection to this input.

Inputs and Equations

At this point we have a simple open box. However changing it's size is inconvenient since the dimensions of our two rectangles are unrelated.

Add three input atoms from the left menu. Each needs a distinct name, let's go with width, depth, height.

Additionally create a Constant atom, also from the left menu. Let's name this "WallThickness" and set it to 1.

Click on the background of the flow canvas an you can now see that the input atoms show up as adjustable numeric values in the bottom left control pane.

There are a number of ways to use these inputs.

1. Drag a connector from "width" input to the "x length" input on our first rectangle
2. Click on the first rectangle and overwrite your "y length" number with the text "height" <- capitalization needs to match the input atom's name.
3. On the smaller rectangle, overwite your "x length" value with "width - 2 * WallThickness". In addition to addition and multiplication, operations like abs, sin, cos, tan, atan, etc are all allowed in numeric inputs.

Additionally update the extrude heights and the z-move in your project to ensure it's fully parameterized.

Github Molecules

In addition to the Atoms provided by Abundance, you can import other Users public projects as Molecules. Some of these projects are objects (like our box example) and some are tools.

Add a Github Molecule atom from the top-right menu. This molecule searches all public projects by name and readme description. We're going to import a project called "Fillet_SidesOnly". Once imported you'll see this project appear as another molecule in your flow panel.

Drag a connector from the difference output to the "InputShape" input on Fillet_SidesOnly. Adjust the fillet radius as you deem fit.

If you'd prefer different fillet behavior there are many other existing fillet projects. I'd suggest looking at "selected.Fillet" as a more customizable option.

Exports

Add an export atom from the top right menu. Drag a connection from Difference output to the "geometry" input on the export.

Run Mode

Run mode allows anyone to view Abundance projects without logging in. This is the public face of all your non-private projects.

Click the arrow on the top-right of the 3D view panel to go to Run Mode. This view of your project can be shared via url.

Notice that the "input" atoms of your project are rendered as user-modifiable values in this view. Changing them will update the project. Additionally, any export atoms in your project are rendered here as "Export <...>" buttons the user can click to download the linked component of your project in the format you selected.

Additionally, from here other users of Abundance can fork your project to make deeper modifications. See the section on Forking and Pull Requests below.

Working with an AI Agent

An AI agent running on your computer, such as Claude Code, can look at and edit the project open in Abundance. It can list atoms, read errors, render images of parts, export files, change parameters, write code atoms, and wire atoms together.

1. Start the agent bridge. Claude Code starts it automatically from this repository's .mcp.json. See bridge/README.md for other setups.
2. In Abundance, open Connect an AI agent: the sparkle button on the right in Run Mode, or AI Agent in the menu in Create Mode. Adding #agent to the end of the page address opens it too.
3. Paste the bridge's pairing token and turn on Connect local AI agent.

The agent starts read-only. To let it make changes, tick Allow edits in the AI agent chip at the top of the window. Each change the agent makes is one step you can undo, labeled "AI:". While edits are allowed, autosave pauses, and the agent can only save after you confirm. Use Chrome or Firefox, since Safari blocks this connection.

Shapes

Regular Polygon

The regular polygon atom creates a regular polygon shape. Regular polygons are regularly extruded to create a 3D shape.

Circle

The circle atom creates a circle sketch on the XY plane. Circle shapes are commonly extruded to create cylinders.

Rectangle

The rectangle atom creates a rectangle sketch on the XY plane. Rectangles are commonly extruded to make a 3D shape.

Text

The text atom creates a basic sketch on the XY plane with a string of your choosing. Text is commonly extruded to make a 3D shape.

Molecule

The molecule atom can contain any number of atoms in a useful configuration. To add inputs to the molecule, place an input atom within it.

Interactions

Intersection

The intersection atom computes the area of intersection of two shapes and creates a new shape out of that area.

Difference

The difference atom subtracts one shape from another.

Join

Assembly

The assembly selector allows multiple shapes to be combined into one unit called an assembly. The order in which atoms are combigned matters because where shapes intersect shapes earlier in the order subtract from shapes later in the order. For example if you have a bolt which needs to create a hole in a part you should assemble first the part and then the bolt.

Fusion

The fusion selector atom allows multiple shapes to be combined into one unit. The shapes are fused, become one and are inseparable from then on.

Shrinkwrap

The shrinkwrap atom combines multiple sketches into a single shape as if they had been shrinkwrapped. This is useful for creating shapes that would be difficult to create in other ways.

Loft

Actions

Color

The color atom gives color to a 2D or 3D shape.

Move

The move atom moves a 3D shape in 3D space or a 2D shape in 2D space.

{

Extrude

The Extrude atom takes a 2D shape and makes it 3D.

Rotate

The rotate atom rotates a shape along any of its three axis.

Scale

The scale function scales a 2D or 3D shape by a specified factor. A scale factor of 1.0 keeps the original size, 2.0 doubles the size, and 0.5 halves the size. The Scale function can be used in the Code atom and works with both individual geometries and assemblies.

Example usage in Code atom:

// Scale a shape to 150% of its original size
let scaledShape = Scale(library[inputShape], 1.5);
return scaledShape;

Tags

README

The README atom provides notes to the next person reading the project. The text of the readme input is added to the readme page of the project (similar to this page you are reading now).

Tag

The tag atom adds a tag to a part which can be later used to retrieve that part from an assembly.

Add BOM Tag

The Add BOM Tag atom tags a part with a bill of materials item. This item will appear in the project bill of materials one time each time the tagged part appears in the final shape. For example, if you have a table leg that needs four bolts, and the final model has four table legs, the bolt will automatically appear in the final bill of materials 16 times.

Inputs

Input

The input atom lets you define which variables are inputs to your program. They function similar to constants, however when you share your project, the person on the other end will have the ability to change the values of the inputs. Inputs placed within a molecule will add inputs to that molecule up one level.

Code

The code atom allows you to enter arbitrary replicad code. For all available methods see replicad.xyz

Constant

The constant atom defines a constant number that can be used to control multiple inputs.

Equation

The equation atom lets you perform math operations on numbers produced by constants and inputs. The equation atom uses the mathjs library to evaluate mathematical expressions.

Supported Math Functions

The equation atom supports a wide range of mathematical operations:

Basic Arithmetic Operators:

• + (addition), - (subtraction), * (multiplication), / (division)
• % (modulo), ^ (power/exponentiation)

Mathematical Constants:

• pi or PI - π (3.14159...)
• e or E - Euler's number (~2.718)
• tau - Circle constant (2π)
• Infinity - Positive infinity
• NaN - Not a Number

Arithmetic Functions:

• sqrt(x) - Square root
• pow(x, y) - Power (x raised to y)
• abs(x) - Absolute value
• ceil(x) - Round up to nearest integer
• floor(x) - Round down to nearest integer
• round(x) - Round to nearest integer
• exp(x) - Exponential (e^x)
• log(x) - Natural logarithm
• log10(x) - Base-10 logarithm
• log2(x) - Base-2 logarithm
• sign(x) - Sign of a number (-1, 0, or 1)
• cube(x) - Cube of a number
• square(x) - Square of a number
• cbrt(x) - Cube root

Trigonometric Functions:

• sin(x), cos(x), tan(x) - Basic trig functions (x in radians)
• asin(x), acos(x), atan(x) - Inverse trig functions
• atan2(y, x) - Two-argument arctangent
• sinh(x), cosh(x), tanh(x) - Hyperbolic functions

Statistical Functions:

• min(a, b, ...) - Minimum value
• max(a, b, ...) - Maximum value
• mean(a, b, ...) - Average value
• median(a, b, ...) - Median value
• sum(a, b, ...) - Sum of values
• std(a, b, ...) - Standard deviation

Comparison Operators:

• <, <=, >, >= - Comparison
• ==, != - Equality

Logical Operators:

• && (and), || (or), ! (not)

Example Equations:

x + y                    // Add two inputs
2 * pi * r              // Calculate circumference
sqrt(x^2 + y^2)         // Distance formula
sin(angle * pi / 180)   // Convert degrees to radians and calculate sine
max(width, height)      // Get maximum of two values

Variables in equations automatically become inputs to the atom. For example, if you enter x + y, two inputs named x and y will be created automatically.

Import/Export

Gcode

The Gcode atom generates Maslow CNC gcode from input geometry. It can process both single parts and assemblies, automatically extracting and sorting parts in the specified direction. The atom provides configuration options for tool size, number of passes, cutting speed, and cut-through depth. Once generated, the gcode can be downloaded using the built-in download button.

For assemblies, the Gcode atom extracts individual parts, sorts them based on the selected direction (Left, Right, Top, or Bottom) using bounding boxes, and generates sequential gcode for each part. It also ensures that interior parts are cut before their containing exterior parts to prevent collision issues.

Import

The Import atom allows you to upload a STL, SVG, or STEP file. Complex models might take a long time to compute.

Export

The export atom tags a part for export. An Export atom lets you download the selected part in a file format of your choosing and makes that part available for download in Run Mode.

GitHub Molecule

The GitHub atom type is not directly available. By clicking on the GitHub tab when placing a new Atom, you can search for and add any other Abundance project to your project as a molecule.

Output

The output atom cannot be directly placed; however, each molecule has one output that can't be deleted. Connect a shape to the output of a molecule to make that shape available one level up. The output of the top-level molecule is the output of the project.

How to contribute to the Abundance project.

Setup Instructions

Prerequisites

• Node.js 20.x or higher
• npm (comes with Node.js)
• Git

Clone and Install

1. Clone the repository:

   git clone https://github.com/BarbourSmith/Abundance.git
   cd Abundance
   

2. Install dependencies:

   npm install --legacy-peer-deps
   

   ⚠️ Important: Always use the --legacy-peer-deps flag when installing dependencies.

3. Configure for local development:

   Edit .env file - uncomment the dev section:

   # Uncomment these lines for local development:
   VITE_APP_DEV = "/"
   VITE_REDIRECT_URI = "http://localhost:4444/"
   VITE_GH_OAUTH_CLIENT_ID = "Ov23liN8Q3iGPXSUHUsH"
   

   Edit vite.config.js - change the base path:

   base: "/", // Change from "/Abundance" to "/" for local development
   

4. Start the development server:

   npm start
   

   The application will be available at http://localhost:4444

Available Scripts

• npm start - Start the Vite development server on port 4444
• npm run build - Build the production bundle to dist/ folder
• npm run serve - Preview the production build locally
• npm run unit - Run unit tests with Vitest
• npm test - Run end-to-end Puppeteer tests
• npm run coverage - Generate test coverage report
• npm run test:bridge - Test the local AI agent bridge
• npm run test:bridge:e2e - Drive a live project through the agent bridge (needs npm start)
• npm run bridge:token - Print the pairing token for the AI agent bridge

Testing

Unit Tests

Unit tests use Vitest and test core CAD functionality:

npm run unit

Tests cover:

• Geometry operations (shapes, extrude, interactions)
• CAD functions (rotation, translation, boolean operations)
• Code execution and validation
• BOM (Bill of Materials) functionality

End-to-End Tests

E2E tests use Puppeteer to test the complete application:

# Install Playwright browsers (first time only)
npx playwright install chromium

# Run E2E tests
npm test

Note: The development server must be running before executing E2E tests.

Building

Build the production bundle:

npm run build

This creates an optimized production build in the dist/ directory. The build process:

• Bundles all assets and code
• Minifies JavaScript and CSS
• Copies index.html to 404.html for GitHub Pages SPA routing
• Generates source maps

Deployment

The application is automatically deployed to GitHub Pages when changes are pushed to the main branch via GitHub Actions (.github/workflows/Actions.yaml).

Manual deployment:

npm run deploy

The live application is available at: https://abundance.maslowcnc.com

Troubleshooting

Build Issues

Problem: Build fails with dependency errors

npm install --legacy-peer-deps

Problem: vitest: not found or missing binaries

# Clean install
rm -rf node_modules package-lock.json
npm install --legacy-peer-deps

Testing Issues

Problem: Puppeteer/Playwright browser not found

npx playwright install chromium

Problem: E2E tests fail to connect

• Ensure the development server is running (npm start)
• Check that port 4444 is not in use by another application

Development Server Issues

Problem: Port 4444 already in use

# Kill the process using port 4444
lsof -ti:4444 | xargs kill -9

Problem: OAuth login not working locally

• Verify .env has correct local development settings
• Ensure VITE_REDIRECT_URI matches your local URL

Common Warnings

These warnings are expected and do not affect functionality:

• rimraf deprecation warnings
• react-three-fiber deprecation (replaced by @react-three/fiber)
• 4 npm audit vulnerabilities (peer dependency related)

Technology Stack

• Frontend Framework: React 18.2.0
• Build Tool: Vite 5.1.6
• 3D CAD Engine: replicad 0.16.1 (OpenCascade-based)
• 3D Rendering: Three.js 0.161.0 with @react-three/fiber
• Authentication: GitHub OAuth
• Testing: Vitest (unit tests) & Puppeteer (E2E tests)
• Deployment: GitHub Pages

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: npm run unit && npm test
5. Build the project: npm run build
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

Code Style

• Follow existing code patterns
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting PR

Support

• Issues: GitHub Issues
• Website: abundance.maslowcnc.com
• Documentation: See this README and in-app help

License

Abundance is licensed under the GNU General Public License v3.0 or later. See LICENSE.

---

Built with ❤️ by the Maslow CNC community