DOCSEARCHbyAlgolia
Submit Docs

cq-gridfinity

repository·main·Indexed 41 days ago

https://github.com/michaelgale/cq-gridfinity

A Python library built on CadQuery for programmatically generating Gridfinity-compatible storage components. It provides a Python API and CLI tools to create customizable boxes, baseplates, drawer spacers, and rugged boxes with features like dividers, magnet holes, and interlocking joints. Supports exporting geometry to STEP, STL, and SVG formats.

Tokens
5.5K
Snippets
15
Records
19
Agent score
51%

What's inside cq-gridfinity

  1. Develop with VS Code Dev Container

    main

    The project includes a Dev Container configuration to provide a consistent environment with Python 3.12, CadQuery 2.4, and all required dependencies (pytest, black, flake8, etc.) pre-installed.

    Prerequisites:

    1. Install Docker Desktop
    2. Install Visual Studio Code
    3. Install the Dev Containers extension in VS Code

    Steps:

    1. Clone the repository:
      git clone https://github.com/michaelgale/cq-gridfinity.git
cd cq-gridfinity
    2. Open in VS Code:
      code .
    3. When prompted, click "Reopen in Container". Alternatively, use the Command Palette (F1 or Ctrl+Shift+P) and select "Dev Containers: Reopen in Container".

    Troubleshooting:

    • Ensure Docker is running.
    • If issues persist, select "Dev Containers: Rebuild Container" from the Command Palette.
    git clone https://github.com/michaelgale/cq-gridfinity.git
cd cq-gridfinity
code .

  2. Install a lid window in a GridfinityRuggedBox

    main

    To install a transparent acrylic window into a printed GridfinityRuggedBox lid, follow these steps:

    1. Prepare the window: Cut an acrylic sheet to the dimensions provided by lid_window_size(). It is recommended to chamfer or round off the leading edge corners with a file.
    2. Insert: Slide the window into the lid starting from the back, following the tapered window groove slot around the inside perimeter.
    3. Position: Slide it just past the retention slots for the hinges.
    4. Secure:
      • Option A (Screws): Secure with 3x M2 screws along the back of the lid. You must carefully drill 2.5 mm clearance holes into the window in situ before installing screws.
      • Option B (Glue): Secure with a few drops of super glue along the rear edge.
    5. Hinges: Install the lid hinges last; they act as the physical retainer for the back edge of the window.

  3. Install cq-gridfinity

    main

    You can install cq-gridfinity via PyPI or directly from the source.

    Dependencies:

    Via PyPI:

    $ pip install cqgridfinity

    Via Source:

    $ git clone https://github.com/michaelgale/cq-gridfinity.git
$ cd cq-gridfinity
$ pip install .
    pip install cqgridfinity

  4. Configure GridfinityRuggedBox options

    main

    The GridfinityRuggedBox is highly customizable via keyword arguments.

    ArgumentDescription
    lid_heightLid height (should be multiple of 10 mm for stacking)
    wall_vgroovesEnable horizontal v-grooves to body shell
    front_handleEnable front handle
    stackableAdd mating stackable features
    side_claspsAdd extra side latching clasps
    lid_baseplateEnable top/lid baseplate
    inside_baseplateEnable interior baseplate
    side_handlesEnable side handles to box
    front_labelEnable front label panel
    label_lengthLength of front label panel (None for auto size)
    label_heightHeight of front label panel (None for auto size)
    label_thThickness of label panel, default is GR_LABEL_TH
    back_feetAdd rear back feet matching hinges to allow the box to stand vertically
    hinge_widthSize of hinge, default is GR_HINGE_SZ (32 mm)
    hinge_boltedUse bolted hinge construction (True) or printed (False)
    box_colorColor for the assembly STEP file (uses cq.Color)
    lid_colorColor for the lid
    handle_colorColor for the handle
    latch_colorColor for the latch
    hinge_colorColor for the hinge
    label_colorColor for the label
    window_thThickness of the lid window material
    side_handlesEnable side handles to box

  5. Configure GridfinityDrawerSpacer options

    main

    When initializing or configuring a GridfinityDrawerSpacer, you can use the following keyword arguments to customize the spacer components:

    ArgumentDescription
    thicknessThickness of spacers, default is GR_BASE_HEIGHT (5 mm)
    chamf_radChamfer radius of spacer top/bottom edges
    show_arrowsShow orientation arrows indicating drawer in/out direction
    align_featuresAdd "jigsaw" interlocking features
    align_tolTolerance of the interlocking joint
    align_minMinimum spacer width for adding interlocking feature
    min_marginMinimum size to make a spacer; nothing is made for smaller gaps
    toleranceOverall tolerance for spacer components, default is GR_TOL (0.5 mm)

  6. Use cq-gridfinity in Python scripts

    main

    You can import cqgridfinity to programmatically generate Gridfinity objects using CadQuery. This allows for high customization, such as adding custom cutouts or text labels.

    Example of creating and saving a simple box:

    from cqgridfinity import *

# make a simple box
box = GridfinityBox(3, 2, 5, holes=True, no_lip=False, scoops=True, labels=True)
box.save_stl_file()
# Output: gf_box_3x2x5_holes_scoops_labels.stl
    from cqgridfinity import *

# make a simple box
box = GridfinityBox(3, 2, 5, holes=True, no_lip=False, scoops=True, labels=True)
box.save_stl_file()

  7. Use GridfinityObject methods for file export and naming

    main

    The GridfinityObject base class (used by GridfinityBox, GridfinityBaseplate, etc.) provides methods to generate descriptive filenames and export geometry to various formats.

    Generating Filenames

    Use obj.filename(prefix=None, path=None) to get a string containing the object's dimensions and enabled features (e.g., gf_box_3x2x5_holes).

    Exporting Files

    You can export the object directly using:

    • obj.save_step_file(filename=None, path=None, prefix=None)
    • obj.save_stl_file(filename=None, path=None, prefix=None)
    • obj.save_svg_file(filename=None, path=None, prefix=None)

    Note on Automatic Naming: The export methods are aware of the last object generated by a specific render method. If you call a render method (like render_handle()) and then call a save method, the filename will automatically include the feature name (e.g., _handle) in the exported file.

    box = GridfinityBox(3, 2, 5, holes=True)
box.filename() # 'gf_box_3x2x5_holes'

# Exporting after rendering a specific part
b1 = GridfinityRuggedBox(5, 4, 6)
b1.render_handle()
b1.save_stl_file() # saved as 'gf_ruggedbox_5x4x6_handle_...'

  8. Use GridfinityRuggedBox to create parameterized storage boxes

    main

    The GridfinityRuggedBox class allows you to generate fully parameterized, Gridfinity-compatible rugged storage boxes. It is a code-based derivative of Pred's design on Printables.

    Rendering Modes

    You can render the box in several ways depending on your needs:

    • render_assembly(): Renders the complete assembly.
    • render(): Renders only the main box body shell.
    • render_lid(): Renders only the lid.
    • render_accessories(): Renders accessory components (hinges, latches, etc.) in required quantities.
    • Individual components: You can also call render_hinge(), render_latch(), render_label(), or render_handle() to get single parts.

    Lid Window Feature

    You can substitute the lid baseplate with a window for visibility. The window uses a 1 mm thick transparent acrylic sheet.

    • Use lid_window_size() to query the required dimensions for the acrylic.
    • Set window_th to adjust the expected thickness of the window material (recommended range: 0.8 to 1.6 mm).
    # Example usage is implied by the class description
# To get window dimensions for an acrylic insert:
# window_size = box.lid_window_size()

  9. Use GridfinityDrawerSpacer to create drawer spacers

    main

    The GridfinityDrawerSpacer class generates components to secure Gridfinity baseplates snugly inside drawers of arbitrary dimensions. It calculates the best fit for integer Gridfinity units and creates corner sections, side spacers, and front/back spacers to fill the remaining gaps.

    Key features:

    • Automatic sizing: Computes the best fit of integer Gridfinity baseplate units based on provided width and depth.
    • Interlocking design: Uses "jigsaw" type features (align_features=True) to assist assembly.
    • Orientation aids: Includes optional alignment arrows (show_arrows=True) to indicate the drawer's movement direction.
    • Printing optimization: Use render_half_set() to arrange components compactly for 3D printing; you can print this set twice to get a full set for one drawer.
    • Thresholding: If a gap is smaller than min_margin (default 4 mm), no spacer is generated for that dimension.
    # make drawer spacers for Craftsman tool chest drawer 23" wide x 19" deep
spacer = GridfinityDrawerSpacer(582, 481, verbose=True)

# Example for IKEA ALEX narrow drawer
spacers = GridfinityDrawerSpacer(INCHES(11.5), INCHES(20.5), verbose=True)
spacers.render_full_set(include_baseplate=True)
spacers.save_step_file("ikea_alex_full_set.step")

# make a half set for 3D printing
spacers.render_half_set()
spacers.save_stl_file("ikea_alex_half_set.stl")

  10. Access GridfinityObject properties and CadQuery objects

    main

    When working with GridfinityObject instances, you can access the following properties to retrieve dimensions or the underlying CadQuery geometry:

    • obj.cq_obj: Returns the rendered CadQuery Workplane object.
    • obj.length: Returns the length in mm.
    • obj.width: Returns the width in mm.
    • obj.height: Returns the height in mm.
    • obj.top_ref_height: Returns the height of the top surface of a solid box or the floor height of an empty box. This is useful for orienting custom cutouts or tools to the correct height.

  11. Use the GridfinityBox class

    main

    The GridfinityBox class creates parameterized Gridfinity boxes. Dimensions are provided in 3D units: length and width are multiples of 42 mm, and height is a multiple of 7 mm.

    Core Configuration Options:

    • lite_style: If True, creates a simplified, homogenous 1 mm thick walled shell (faster printing, less material). Note: lite_style cannot be combined with solid boxes, finger scoops, or magnet holes.
    • holes: Boolean to add magnet holes to the bottom.
    • unsupported_holes: If True, uses a 3D-printer friendly hole style with thin filler strips to avoid needing supports.
    • no_lip: Boolean to remove the top mounting lip feature.
    • scoops: Boolean to add finger scoops.
    • scoop_rad: Radius of the interior scoops.
    • labels: Boolean to add a label flange to the top.
    • label_width: Width of the label strip.
    • label_height: Thickness height of label overhang.
    • label_lip_height: Thickness of label vertical lip.
    • length_div: Number of dividing walls along the length.
    • width_div: Number of dividing walls along the width.
    • solid: Boolean to make the box partially solid.
    • solid_ratio: Ratio of solid height (0.0 to 1.0).
    • wall_th: Wall thickness (0.5-2.5 mm).
    • fillet_interior: Boolean to enable/disable internal fillet edges.
    # Create a simple 3 x 2 box, 5U high
box = GridfinityBox(3, 2, 5)
box.save_step_file()

# Create a "lite" style 3 x 2 box, 5U high
box = GridfinityBox(3, 2, 5, lite_style=True)

# Add magnet holes with printer-friendly unsupported style
box = GridfinityBox(1, 1, 5, holes=True, unsupported_holes=True)

# Add dividing walls, scoops, and labels
box = GridfinityBox(3, 2, 5, length_div=2, width_div=1, scoops=True, labels=True)

# Create a partially solid box
box = GridfinityBox(3, 2, 5, solid=True, solid_ratio=0.7)

  12. Use the GridfinityBaseplate class

    main

    The GridfinityBaseplate class creates basic Gridfinity baseplates (Zach Freedman style) without magnet or mounting holes.

    Key Attributes:

    • ext_depth: Extended depth to extrude below the baseplate.
    • straight_bottom: Boolean to add/remove a 0.8 mm chamfer on the bottom.
    • corner_screws: Boolean to add corner mounting screw tabs.
    • corner_tab_size: Size of screw mounting tab (mm).
    • csk_hole: Hole diameter of countersink mounting screw (mm).
    • csk_diam: Countersink diameter (mm).
    • csk_angle: Countersink angle (deg).
    # Create 4 x 3 baseplate
baseplate = GridfinityBaseplate(4, 3)
baseplate.save_step_file()
# Output: gf_baseplate_4x3.step