MechanicsSketches Skill

You can generate engineering mechanics sketches programmatically using the MechanicsSketches Python library.

Setup

Install the library via pip:

pip install git+https://github.com/MatthiasHBusch/MechanicsSketches.git

Or install dependencies manually and add to PYTHONPATH:

pip install matplotlib PyQt5
export PYTHONPATH="/path/to/parent/of/MechanicsSketches:$PYTHONPATH"

Quick Start — Writing a Script

Create a Python script that builds a sketch and renders it:

from MechanicsSketches import *
import os

sketch = create_sketch("My Sketch")
S = 30.0  # Scale factor (recommended: 20-40)

# Add components
add_beam(sketch, ax=0, ay=0, bx=10*S, by=0, scale_factor=S)
add_pinned_support(sketch, cx=0, cy=0, angle_deg=0, scale_factor=S)
add_roller_support(sketch, cx=10*S, cy=0, angle_deg=0, scale_factor=S)
add_force(sketch, cx=5*S, cy=0, angle_deg=0, scale_factor=S, annotation=r"$F$")

# Render
script_dir = os.path.dirname(os.path.abspath(__file__))
render(sketch, filename=os.path.join(script_dir, "output.pdf"), dpi=300)

Then run: python my_sketch.py

Quick Start — Using the Helper Script

Alternatively, use the bundled helper to render from JSON:

python scripts/generate_sketch.py input.json output.pdf

Key Concepts

Scale Factor (S)

All positions and sizes should be multiples of S (typically 30.0). This keeps proportions consistent across components.

Angle Convention

• angle_deg=0 → default orientation (upward for supports/forces, horizontal for dimensions)
• Angles rotate counterclockwise in degrees

Available Components

| Function | Description | Key Parameters |

|----------|-------------|----------------|

| add_beam(sketch, ax, ay, bx, by, scale_factor) | Rectangular beam A→B | Endpoints, scale |

| add_truss(sketch, ax, ay, bx, by, scale_factor) | Line member A→B | Endpoints, scale |

| add_pinned_support(sketch, cx, cy, angle_deg, scale_factor) | Fixed-position support (triangle) | Center, angle, scale |

| add_roller_support(sketch, cx, cy, angle_deg, scale_factor) | Sliding support | Center, angle, scale |

| add_fixed_support(sketch, cx, cy, angle_deg, scale_factor) | Clamped wall support | Center, angle, scale |

| add_hinge(sketch, cx, cy, scale_factor) | Joint circle | Center, scale |

| add_force(sketch, cx, cy, angle_deg, scale_factor, annotation, ...) | Force arrow | Center, angle, scale, label |

| add_moment(sketch, cx, cy, angle_deg, scale_factor, annotation, ...) | Curved moment arrow | Center, angle, scale, label |

| add_dimension_arrow(sketch, cx, cy, length, angle_deg, scale_factor, annotation, ...) | Double-headed dimension | Center, length, angle, scale, label |

| add_dimension_thickness(sketch, cx, cy, thickness, angle_deg, scale_factor, annotation, ...) | Inward dimension arrows | Center, thickness, angle, scale, label |

| add_coordinate_system(sketch, cx, cy, angle_deg, scale_factor, ax1, ax2, ax3, ...) | x-y-z axes | Center, angle, scale, axis labels |

| add_text(sketch, x, y, text, fontsize, name, rotation) | Text annotation | Position, text, font size |

Annotation Parameters

Force, moment, and dimension functions accept:

• annotation — LaTeX string (e.g., r"$F$", r"$M_A$")
• fontsize_scale — relative font size (default 1.0)
• offsetx, offsety — label position offset
• rotate_annotation — rotate label with component (default False)

Primitives

For custom shapes, use:

• make_line(x0, y0, x1, y1, linewidth, layer, edgecolor)
• make_circle(x, y, r, linewidth, layer, facecolor, edgecolor)
• make_polygon(points, linewidth, layer, facecolor, edgecolor)
• make_arc(x, y, width, height, theta1, theta2, angle, linewidth, layer)
• make_text(x, y, text, fontsize, layer, color, ha, va, rotation)
• make_rectangle(x0, y0, x1, y1, ...)

Add to sketch via add_to_sketch(sketch, primitive).

Transformations

• translate(obj, dx, dy) — move by offset
• rotate(obj, cx, cy, angle_deg) — rotate around point
• scale(obj, cx, cy, factor) — scale from center

All return new objects (non-destructive). Can be chained.

Rendering

render(sketch, filename="output.pdf", dpi=300)  # Qt renderer (default, recommended)
mpl_render(sketch, filename="output.pdf")        # Matplotlib fallback (deprecated, text scaling issues)

Supported formats: .pdf, .png, .jpg, .svg

Tips for the Agent

1. Always define S = 30.0 as the scale factor
2. Place beams first, then supports at endpoints, then loads
3. Use LaTeX for annotations: r"$F$", r"$M_0$", r"$\ell$"
4. For detailed API signatures, see references/api_reference.md
5. The render() function requires a filename — it does not display interactively
6. Do not use mpl_render() — it is deprecated due to text scaling issues. Always use render().

External Endpoints

This skill makes no network requests. All processing is done locally.

Security & Privacy

• No data leaves your machine. The skill only reads local JSON files and writes local image/PDF output.
• No API keys or credentials are required.
• No telemetry or analytics.
• The helper script (scripts/generate_sketch.py) only reads the input file specified by the user and writes to the specified output path.

Trust Statement

This skill is developed and maintained by MatthiasHBusch. The source code is fully open under the MIT license. All functionality runs locally with no external dependencies beyond standard Python packages (matplotlib, PyQt5).