Tutorial: Gear

Tutorial: Gear

Level: Advanced | Time: 10 minutes | Tools used: execute_code, measure, export_model

Goal

Create a module-2, 24-tooth involute spur gear with an 8 mm bore hole and 12 mm face width. This tutorial demonstrates how the AI uses execute_code to run a complete parametric Python script when the built-in primitive tools are not sufficient.

What You Will Build

A standard involute spur gear suitable for 3D printing or CNC machining. The tooth profile follows the involute curve, which is the standard for meshing spur gears.

Background: Gear Geometry

Before starting, it helps to understand the key terms:

Parameter	Symbol	Formula	Value for this gear
Module	m	(chosen)	2 mm
Number of teeth	z	(chosen)	24
Pitch diameter	d	m * z	48 mm
Tip diameter	d_a	m * (z + 2)	52 mm
Root diameter	d_f	m * (z - 2.5)	43 mm
Pressure angle	alpha	(standard)	20 degrees
Face width	b	(chosen)	12 mm
Bore diameter	d_b	(chosen)	8 mm

The module controls the tooth size. A module-2 gear has teeth about 2 mm tall from root to tip (actually pi * m in circular pitch). The pressure angle (20 degrees) is the standard angle at which the involute curve contacts a mating gear.

Steps

Step 1: Set Up

1. Switch to the FreeCAD AI workbench
2. Confirm Act mode is enabled
3. Create a new document: File > New
4. Select a capable model -- gear generation requires the AI to write and execute a substantial Python script

Step 2: Request the Gear

Type in the chat panel:

Create a spur gear: module=2, teeth=24, bore=8mm, face_width=12mm

If you have the gear skill installed, you can also use:

/gear module=2 teeth=24 bore=8mm face_width=12mm

Step 3: Understand the Construction

The AI generates a Python script and runs it via execute_code. Here is what the script does, step by step:

3a. Calculate derived dimensions

The script computes pitch diameter, tip diameter, root diameter, base circle diameter, and tooth spacing from the input parameters. All values derive from the module and tooth count using standard gear formulas.

3b. Generate involute curve points

The involute of a circle is the curve traced by the end of a taut string unwinding from the base circle. The script computes points along this curve:

def involute_point(base_r, angle):
    x = base_r * (math.cos(angle) + angle * math.sin(angle))
    y = base_r * (math.sin(angle) - angle * math.cos(angle))
    return x, y

It samples enough points (typically 20-30) to produce a smooth BSpline.

3c. Create one tooth profile

Each tooth is built from:

• Two involute curves (left and right flanks), mirrored about the tooth centerline
• An arc at the tip connecting the two flanks
• An arc at the root connecting to the adjacent tooth

These curves form a closed wire for one tooth space.

3d. Extrude to face width

The tooth profile is extruded 12 mm along the Z axis to create a solid tooth.

3e. Pattern all teeth

The single tooth is copied and rotated 24 times around the Z axis at 15-degree intervals (360/24 = 15). This creates all teeth.

3f. Fuse with root cylinder

A cylinder at the root diameter is created and fused with all the teeth to form a single solid gear body.

3g. Cut the bore hole

A cylinder of 8 mm diameter is subtracted from the center to create the bore.

Step 4: Inspect the Gear

Once the script completes, you should see a gear in the viewport. Verify it:

Check dimensions:

Measure the bounding box of the gear

Expected result: approximately 52 x 52 x 12 mm (tip diameter x tip diameter x face width).

Count teeth visually:

Rotate the viewport to look at the gear from above (View > Standard Views > Top or press numpad 2). Count the teeth -- there should be 24.

Check the bore:

Measure the bore diameter

Or zoom into the center hole and visually confirm it looks correct relative to the gear.

Step 5: Modify the Gear

You can ask for modifications after the gear is built:

Add a keyway:

Add a 3x3mm keyway to the bore hole

The AI will cut a rectangular slot into the bore for a standard key.

Add a hub:

Add a 20mm diameter, 5mm tall hub on one side

Change parameters:

For a different gear, start a new document and request different values:

Create a spur gear: module=1.5, teeth=32, bore=6mm, face_width=10mm

Step 6: Export

Export the gear to /tmp/gear-m2-z24.step

STEP format is strongly recommended for gears because STL tessellation can distort the involute curves. If you must use STL, request a fine mesh:

Export the gear to /tmp/gear-m2-z24.stl with fine tessellation

Gear Parameters Reference

Common gear configurations for reference:

Application	Module	Teeth	Pitch dia.	Typical bore
Small hobby servo	0.5	20	10 mm	3 mm
RC car drivetrain	1.0	15-30	15-30 mm	5 mm
Robotics	1.5	20-40	30-60 mm	6-8 mm
Light machinery	2.0	20-50	40-100 mm	8-12 mm
Industrial	3.0+	30-80	90-240 mm	15-30 mm

Meshing rule: Two gears mesh correctly when they have the same module and pressure angle. The center distance equals (z1 + z2) * m / 2.

Limitations

• Helical gears are not yet supported by the built-in skill. You can request one in chat and the AI will attempt to generate the script, but results may vary.
• Very small modules (below 0.5) may produce geometry that is too fine for FreeCAD's default tolerance. Increase precision in FreeCAD settings if needed.
• Large tooth counts (above 80) increase script execution time significantly due to the number of boolean fuse operations.

What You Learned

Concept	Details
execute_code	The AI can write and run arbitrary FreeCAD Python scripts for complex geometry
Parametric design	All dimensions derive from a few input parameters (module, teeth, bore, width)
Involute curves	Standard tooth profile geometry computed mathematically
Boolean operations	Fusing teeth with root cylinder, cutting the bore
Limits of primitives	Some shapes require scripted geometry, not just built-in tools

Next Steps

• Create a mating gear (same module, different tooth count) and check that they mesh
• Explore other complex shapes: turbine blades, thread profiles, cam mechanisms
• See Tool Reference for the full list of available tools