Skip to content

docs: new docs #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nullStack65 merged 1 commit into from
Jan 4, 2026
Merged

docs: new docs #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
233 changes: 93 additions & 140 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,17 +1,22 @@
# microfinity
# Microfinity

[![PyPI](https://img.shields.io/pypi/v/microfinity.svg)](https://pypi.org/project/microfinity/)
![python version](https://img.shields.io/static/v1?label=python&message=3.9%2B&color=blue&style=flat&logo=python)
[![CadQuery](https://img.shields.io/static/v1?label=dependencies&message=CadQuery%202.0%2B&color=blue&style=flat)](https://github.com/CadQuery/cadquery)
[![cq-kit](https://img.shields.io/badge/CQ--kit-blue)](https://github.com/michaelgale/cq-kit)
![license](https://img.shields.io/badge/license-MIT-blue.svg)
[![code style: black](https://img.shields.io/badge/code%20style-black-black.svg)](http://github.com/psf/black)

A Python library to make [Gridfinity](https://gridfinity.xyz) compatible objects with [CadQuery](https://github.com/CadQuery/cadquery).
**Gridfinity-compatible storage system with optional sub-grid sizing for more granular bin dimensions.**

The Gridfinity system was created by [Zach Freedman](https://www.youtube.com/c/ZackFreedman) as a versatile system of modular organization and storage modules. This library provides Python classes to create parameterized Gridfinity components including boxes, baseplates, drawer spacers, and rugged storage boxes.
Microfinity extends the [Gridfinity](https://gridfinity.xyz) modular storage system with support for fractional grid units (0.25U and 0.5U increments), allowing you to create bins that better fit your specific items while remaining fully compatible with standard Gridfinity baseplates and bins.

> **Note:** This is a fork of [cq-gridfinity](https://github.com/michaelgale/cq-gridfinity) by Michael Gale.
## Key Features

- **100% Gridfinity Compatible** - All bins work on standard Gridfinity baseplates
- **Fractional Sizing** - Create bins in 0.25U (10.5mm) or 0.5U (21mm) increments
- **Automatic Drawer Layouts** - Generate optimally-segmented baseplates for any drawer size
- **Multi-Piece Baseplates** - Connection clips join pieces that exceed your build plate
- **Parametric Design** - Full control over holes, scoops, labels, dividers, and more
- **Multiple Export Formats** - STEP, STL, and SVG output

## Installation

Expand All @@ -29,183 +34,131 @@ pip install -e .

### Dependencies

- [CadQuery](https://github.com/CadQuery/cadquery)
- [cq-kit](https://github.com/michaelgale/cq-kit)
- [CadQuery](https://github.com/CadQuery/cadquery) (>= 2.0)
- [cq-kit](https://github.com/michaelgale/cq-kit) (>= 0.5.6)

## Quick Start

```python
import microfinity
print(microfinity.__version__)
```
### Create a Standard Box

```python
from microfinity import *
from microfinity import GridfinityBox

# Make a simple box
box = GridfinityBox(3, 2, 5, holes=True, scoops=True, labels=True)
box.save_stl_file()
# Output: gf_box_3x2x5_holes_scoops_labels.stl
# 2x3x4 box with magnets, scoops, and labels
box = GridfinityBox(2, 3, 4, holes=True, scoops=True, labels=True)
box.save_stl_file() # Saves: gf_box_2x3x4_holes_scoops_labels.stl
```

## CLI Commands
### Create a Fractional Box

### `microfinity-box`
```python
from microfinity import GridfinityBox

```bash
microfinity-box 2 3 5 -m -f stl
# 1.25U x 0.5U x 3U box - fits in tighter spaces
box = GridfinityBox(1.25, 0.5, 3, micro_divisions=4)
box.save_stl_file() # Saves: gf_box_1.25x0.50x3_micro4.stl
```

### `microfinity-base`

```bash
microfinity-base 7 4 -s -f stl
```
### Create a Baseplate

### `microfinity-rugged`
```python
from microfinity import GridfinityBaseplate

```bash
microfinity-rugged 5 4 6 --box --lid -f stl
# 4x3 baseplate with corner mounting screws
baseplate = GridfinityBaseplate(4, 3, corner_screws=True)
baseplate.save_stl_file()
```

## Classes

### Geometry Classes

- `GridfinityBox` - Boxes with dividers, scoops, labels, magnet holes
- `GridfinitySolidBox` - Solid boxes without interior cutout
- `GridfinityBaseplate` - Baseplates with optional mounting tabs and notches
- `GridfinityBaseplateLayout` - Tiled baseplate layouts with automatic partitioning for large prints
- `GridfinityConnectionClip` - Connection clips for joining baseplate pieces
- `GridfinityDrawerSpacer` - Spacers for fitting baseplates in drawers
- `GridfinityRuggedBox` - Rugged storage boxes with lids and handles

### Utility Classes

- `GridfinityExporter` - Export utility for STEP, STL, SVG formats
- `SVGView` - Enum for SVG view directions

### Enums

- `EdgeMode` - Edge treatment options for baseplate layouts
- `SegmentationMode` - Partitioning strategies for large baseplates
- `ToleranceMode` - Tolerance handling for baseplate fitting

## Export

The `GridfinityExporter` class provides a unified interface for exporting Gridfinity objects to various file formats.

### Basic Usage
### Generate a Drawer Layout

```python
from microfinity import GridfinityBox, GridfinityExporter, SVGView

# Create a box
box = GridfinityBox(2, 2, 4, holes=True)

# Export using the exporter
exporter = GridfinityExporter(box)
exporter.save_step_file("box.step")
exporter.save_stl_file("box.stl")
exporter.save_svg_file("box.svg", view=SVGView.ISOMETRIC)
```

### Direct Class Methods (Backward Compatible)
from microfinity import GridfinityBaseplateLayout

All geometry classes also have export methods directly available:
# Automatically segment a drawer into printable pieces
layout = GridfinityBaseplateLayout(
drawer_x_mm=450,
drawer_y_mm=380,
build_plate_x_mm=220,
build_plate_y_mm=220,
)

```python
box = GridfinityBox(2, 2, 4)
box.save_stl_file() # Auto-generates filename based on parameters
box.save_step_file("custom_name.step")
box.save_svg_file("preview.svg")
layout.print_summary() # Shows piece breakdown
layout.export_all("./drawer_plates", file_format="stl")
```

### SVG Views
## CLI Commands

The `SVGView` enum provides the following view options:
Generate models directly from the command line:

| View | Description |
|------|-------------|
| `SVGView.FRONT` | Front view (+Y direction) |
| `SVGView.BACK` | Back view (-Y direction) |
| `SVGView.LEFT` | Left view (-X direction) |
| `SVGView.RIGHT` | Right view (+X direction) |
| `SVGView.TOP` | Top view (+Z direction) |
| `SVGView.BOTTOM` | Bottom view (-Z direction) |
| `SVGView.ISOMETRIC` | Isometric view (default) |
```bash
# Standard 2x3x5 box with magnet holes
microfinity-box 2 3 5 -m -f stl

### Export Options
# Fractional 1.25x2x3 box (quarter-grid)
microfinity-box 1.25 2 3 -f stl

```python
exporter = GridfinityExporter(obj)
# 6x4 baseplate with corner screws
microfinity-base 6 4 -s -f stl

# STL with custom tolerance
exporter.save_stl_file("output.stl", tolerance=0.01, angular_tolerance=0.1)
# Generate drawer layout
microfinity-baseplate-layout -d 450 380 -b 220 220 -o ./drawer -f stl

# SVG with custom styling
exporter.save_svg_file(
"output.svg",
view=SVGView.TOP,
line_width=0.5,
show_hidden=False
)
# Generate calibration test prints
microfinity-calibrate -o ./calibration -f stl
```

### Baseplate Layout Export
## The Microgrid System

`GridfinityBaseplateLayout` has additional export methods for batch exporting all pieces:
Standard Gridfinity uses a 42mm grid (1U). Microfinity adds support for smaller increments:

```python
from microfinity import GridfinityBaseplateLayout

layout = GridfinityBaseplateLayout(
length_mm=300,
width_mm=200,
max_piece_u=4
)
| micro_divisions | Pitch | Increment | Use Case |
|-----------------|---------|-----------|----------|
| 1 | 42.0mm | 1U | Standard Gridfinity |
| 2 | 21.0mm | 0.5U | Half-grid sizing |
| 4 | 10.5mm | 0.25U | Quarter-grid sizing |

# Export all pieces and clips
results = layout.export_all(
output_dir="./output",
formats=["stl", "step"],
prefix="my_baseplate"
)
Fractional bins use smaller "micro-feet" that still index properly on standard baseplates:

# Export preview SVGs only
layout.export_preview(output_dir="./previews")
```

## Development

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
Standard 1U bin: Fractional 0.5U bin:
┌────────────────┐ ┌───────┐
│ │ │ │
│ Single 42mm │ │ 21mm │
│ foot │ │ foot │
│ │ │ │
└────────────────┘ └───────┘
```

### Running Tests
See [The Microgrid System](docs/microgrid-system.md) for details.

```bash
# Run all tests
pytest
## Documentation

# Run with coverage
pytest --cov=microfinity
- [Getting Started](docs/getting-started.md) - Installation and first steps
- [The Microgrid System](docs/microgrid-system.md) - How fractional sizing works
- **Components:**
- [Boxes](docs/components/boxes.md) - GridfinityBox parameters and features
- [Baseplates](docs/components/baseplates.md) - GridfinityBaseplate options
- [Layouts](docs/components/layouts.md) - Automatic drawer tiling system
- [Spacers](docs/components/spacers.md) - Drawer spacer generation
- [CLI Reference](docs/cli-reference.md) - Command line tools
- [Calibration](docs/calibration.md) - Test prints for tuning fit
- [Export Options](docs/export.md) - File formats and batch export
- [Python API](docs/python-api.md) - Programmatic usage

# Run specific test file
pytest tests/test_box.py
## Examples

# Update golden test baselines
UPDATE_GOLDEN=1 pytest tests/test_golden.py
```
See the [examples/](examples/) directory for complete scripts:

- `basic_box.py` - Simple box with common features
- `fractional_bins.py` - Various fractional sizes
- `drawer_layout.py` - Complete drawer layout workflow
- `custom_baseplate.py` - Baseplate with specific options
- `batch_export.py` - Generate families of parts

## References
## Credits

- [Gridfinity wiki](https://gridfinity.xyz)
- [Original cq-gridfinity](https://github.com/michaelgale/cq-gridfinity) by Michael Gale
Microfinity is a fork of [cq-gridfinity](https://github.com/michaelgale/cq-gridfinity) by Michael Gale. The Gridfinity system was created by [Zack Freedman](https://www.youtube.com/c/ZackFreedman).

## License

MIT License. Originally created by [Michael Gale](https://github.com/michaelgale).
MIT License - See [LICENSE](LICENSE) for details.
Loading