Projects¶

Group related prints into projects to track multi-part builds, gift sets, or any collection of related prints.

What Are Projects?¶

Projects let you:

• Group prints - Organize related archives together
• Track progress - See completion status
• Set targets - Define how many items needed
• Track quantities - Count items per print for batch printing
• Bill of materials - Track sourced parts (screws, electronics)
• File attachments - Store documentation and references
• Cost tracking - Budget and expense tracking
• Color code - Visual identification
• Add notes - Document the project

Use Cases¶

Creating a Project¶

1. Go to the Projects page
2. Click New Project
3. Fill in the details:

1. Click Create

Adding Archives to Projects¶

From Archive Card¶

1. Right-click an archive card
2. Select Add to Project
3. Choose the project
4. Archive is linked

From Archive Details¶

1. Open an archive
2. Click the Project dropdown
3. Select a project
4. Changes save automatically

Bulk Assignment¶

Assign multiple archives at once using the multi-select toolbar:

1. Click Select button (or Shift+click / Ctrl+click archives)
2. Select the archives you want to assign
3. Click the Project button in the bottom toolbar
4. Choose a project from the list
5. All selected archives are assigned instantly

Progress Tracking¶

Track how close you are to completing a project with separate progress for plates and parts:

Dual Progress Bars¶

When you set both target plates and target parts, you'll see two progress bars:

Plates Progress
[████████░░░░░░░░░░░░] 40%
2 of 5 print jobs

Parts Progress
[████████░░░░░░░░░░░░] 40%
10 of 25 parts

Progress States¶

Plates Progress¶

Tracks the number of print jobs completed:

• Plates Target: 5 with 2 prints done = 40%
• Based on archive count (not quantities)

Parts Progress¶

Tracks the total number of parts/objects printed:

• Parts Target: 25 with 10 parts printed = 40%
• Sum of all archive quantities

Per-File Progress & Complete Sets¶

For projects made of many distinct files that each need to be printed N times (e.g. 13 plates, 10 copies each), set the optional Copies per File target in the project dialog:

• Every printable file in the project's linked folders shows an X / N badge with a mini progress bar: gray = not started, amber = in progress, green = target reached.
• The progress card gains a Complete Sets bar: the minimum per-file count across all printable files — the number of finished assemblies you can ship right now. If 12 of 13 plates are at 3 copies but one is at 2, you have 2 complete sets.
• Without the target, printable files simply show how many times they've been printed (e.g. 3×).

Only completed prints count — failed, cancelled, and in-progress runs don't advance a file's count. Counting is scoped to the project: prints started from the project page or queued from a project-linked File Manager folder are attributed automatically.

Auto-Detection from 3MF¶

When a print is archived, BamBuddy automatically detects how many parts/objects were on the plate:

• Reads slice_info.config from the 3MF file
• Counts non-skipped objects
• Sets the archive quantity automatically

Manual Quantity Override¶

You can still manually adjust the quantity:

1. Open the archive in edit mode
2. Set Items Printed to the correct number
3. Project progress updates automatically

Updating Existing Archives¶

If you have existing archives with quantity=1, run the migration script:

# Preview changes
python scripts/update_archive_quantities.py --dry-run

# Apply changes
python scripts/update_archive_quantities.py

This re-parses all 3MF files to extract the correct object counts.

Color Coding¶

Each project has a color-coded badge:

Available Colors¶

• Red
• Orange
• Yellow
• Green
• Blue
• Purple
• Gray

Badge Display¶

Project badges appear on:

• Archive cards
• Archive list view
• Project overview

Project Cards¶

Each project displays as a card with plates and parts stats:

┌────────────────────────────────────────┐
│  [Color] Voron Build          150/200  │
│                                parts   │
│  Building a Voron 2.4r2 printer       │
│                                        │
│  Plates [████████░░░░] 40%            │
│  20/50 print jobs                      │
│                                        │
│  Parts  [████████████░░░] 75%         │
│  150/200 parts                         │
│                                        │
│  📦 20 plates  🎯 150 parts            │
└────────────────────────────────────────┘

Card Information¶

• Color badge - Visual identification
• Name - Project title
• Progress badge - Parts completed / target
• Plates progress - Print jobs completed
• Parts progress - Objects printed
• Stats footer - Quick view of plates and parts count
• Sub-project count - How many projects sit directly beneath this one
• Part of ... - Which project this one belongs to, when it is a sub-project

Sub-Projects¶

A large build usually is not one flat list. Set a Parent Project on the project dialog and it becomes a sub-project of that one; nesting goes as deep as the work needs, so an assembly can sit under a section which sits under the whole build.

On the Projects Page¶

Sub-projects are not scattered through the grid. A project that has them takes the full width of the row and its sub-projects are drawn inside it, indented behind a rule in the project's own colour:

┌──────────────────────────────────────────────────────────┐
│  [Color] Voron Build                        🗂 2  150/200 │
│  Building a Voron 2.4r2 printer                          │
└──────────────────────────────────────────────────────────┘
   │  SUB-PROJECTS OF VORON BUILD
   │  ┌───────────────────────┐  ┌───────────────────────┐
   │  │ [Color] Frame         │  │ [Color] Toolhead      │
   │  └───────────────────────┘  └───────────────────────┘

The nesting repeats at every level, so a sub-project that has its own sub-projects gets its own rule and its own group.

The Master Project View¶

Open a project that has sub-projects and it gains a second card covering the whole tree:

• Print jobs and parts
• Print time
• Filament used
• Total cost (filament, energy and BOM)
• Progress against every target in the tree added together

Each sub-project listed on the page carries its own branch's totals, not just its own prints. So a sub-project that is itself a parent reports what its whole branch did, and the listed rows add up to the roll-up card minus the master's own prints.

Rules¶

• A project cannot be its own parent, and cannot be moved underneath one of its own sub-projects — that is a loop, not a hierarchy. The parent picker leaves those options out rather than letting you pick one and fail.
• Deleting a project in the middle of a tree lifts its sub-projects up to its own parent. Deleting a top-level project leaves its sub-projects as top-level projects. Nothing beneath a deleted project is deleted with it.
• Archives, queue items and BOM entries belong to the project they were assigned to. Nesting does not move them; it only decides what the roll-up adds together.

Editing Projects¶

1. Click the edit icon on a project card
2. Modify any field
3. Click Save

Editable Fields¶

• Name
• Description
• Color
• Target Plates (print jobs)
• Target Parts (objects)
• Parent Project

Filtering by Project¶

Filter archives to show only those in a project:

1. Go to Archives page
2. Click the Project filter
3. Select a project
4. Only linked archives are shown

Printing Files from a Project¶

If a project has one or more linked library folders, the project detail page lists the printable files from every folder inline — no need to detour through the File Manager to reprint.

What Shows Up¶

Under each linked folder header you'll see a row per file with:

• A thumbnail (if one is available)
• The file name and a type badge (3MF, GCODE, STL, …)
• Print button — only on sliced files (.gcode and .gcode.3mf)

Files that can't be printed directly (.stl, .step, etc.) still appear in the list but without action buttons.

Workflow¶

1. Open the project detail page
2. Find the file under the linked folder you want
3. Click Print
4. Pick your printer, plate, dispatch option, and print options
5. Start the print

Auto-Linking¶

Prints triggered from the project detail page are automatically associated with the originating project. The resulting archive shows up under the project's archive list as soon as the print completes — no manual "Assign to project" step required.

Deleting Projects¶

Deleting a project:

1. Click the delete icon on a project card
2. Confirm deletion

Import & Export¶

Share projects between Bambuddy instances or backup your project data.

Exporting a Single Project (ZIP)¶

Export a complete project bundle including all files from linked library folders:

1. Open the project detail page
2. Click the Export button
3. A ZIP file is downloaded containing:
4. project.json - Project settings, BOM items, and folder metadata
5. files/ - All files from linked library folders

Exporting All Projects (JSON)¶

Export all projects as metadata only (no files):

1. Go to the Projects page
2. Click the Export button in the header
3. A JSON file is downloaded with all project metadata

Importing Projects¶

Import projects from ZIP or JSON files:

1. Go to the Projects page
2. Click the Import button
3. Select a .zip or .json file

ZIP Import:

• Creates the project with all settings
• Creates linked library folders
• Extracts and stores all files from the ZIP
• Files are available in File Manager

JSON Import:

• Creates the project with all settings
• Creates empty linked folders (names only)
• Supports single project or batch import (array of projects)

Project Archives View¶

Click a project card to see all its archives:

• Grid view of all linked prints
• Same filtering and sorting as main Archives
• Quick access to add more prints

Bill of Materials¶

Track non-printed parts needed for your project (screws, electronics, hardware):

Adding BOM Items¶

1. Open a project
2. Scroll to Bill of Materials
3. Click Add Item
4. Fill in the details:

Tracking Acquisition¶

• Check the box when a part is acquired
• Progress bar shows acquired/total items
• Use Hide done to focus on remaining items

File Attachments¶

Attach reference files to your project:

Supported File Types¶

Uploading Files¶

1. Open a project
2. Scroll to Attachments
3. Click Upload or drag and drop
4. Files are stored with the project

Cost Tracking¶

Track project expenses:

Cost Categories¶

• Parts cost - Sum of BOM item prices
• Additional costs - Manual entries for other expenses

Currency¶

Uses your configured currency from Settings → General.

Project Ideas¶