geop_lib_stdlib/

drive.rs

//! The drive train: involute spur gears and their rack, GT2 timing
//! pulleys, shaft collars and flange couplings. Each turns around the `z`
//! axis — the rack runs along it — its datum `axis`.
//!
//! A gear's teeth are what is left of a disc when one gap, patterned round
//! it, is cut away: a boolean per tooth, the price of a tooth count that is
//! a parameter like any other — building a gear takes seconds per tooth.
//! Every gap reaches past the disc on all sides it leaves by, so that no
//! face of it lies on one of the disc's. A rack and a pulley, whose teeth
//! would be cut along one long edge or past two flanges, are each drawn in
//! one profile instead: a rack of at most [`RACK_TEETH`] teeth cut to
//! length, and a pulley family per tooth count.
//!
//! # Meshing
//!
//! Gears of one module mesh with their pitch circles touching: centres
//! `m · (z1 + z2) / 2` apart. Each gear's datum `axis` is a joint's
//! connector; a revolute joint on each, and a `Transmission::Gear`
//! coupling of the two joints with `value = z2 / z1`, the ratio — the
//! first joint's gear turns that many times per turn of the second's — and
//! `reverse`, since external gears turn opposite ways, keeps them in mesh.
//! A rack slides by the arc its pinion's pitch circle rolls off: a
//! `Transmission::RackPinion` coupling of `value = m · z / 2`, the
//! pinion's pitch radius, which its sketch `pitch` draws. Two GT2 pulleys on one belt turn the same way, at the
//! ratio of their tooth counts: a gear coupling without `reverse`.
//!
//! A gear has a tooth centred on `+x`. Two gears whose centres lie along
//! `x` mesh when the second has a gap facing the first: turned half a
//! tooth, `180° / z2`, if `z2` is even, and not at all if it is odd.

use geop_core_math::{geop_error::GeopResult, primitives::FrameAxis};
use geop_ops_extrude_revolve::{Extent, Extents};
use geop_ops_model::Combine;
use geop_ops_model::datums::{origin_axis, origin_plane};
use geop_ops_model::parameters::{Parameter, ParameterKind, Row};
use geop_ops_model::spacing::Spacing;
use geop_ops_pattern::{CircularPatternArgs, Seeds, TurnAxis, body};

use super::{
    StandardPart,
    drawing::Drawing,
    involute::{self, DEGREE, FEWEST_TEETH},
    steps::{
        Around, axis_datum, col, datum_plane, extrude, family, offset_datum, outline_plane,
        plane_datum, profile_plane, revolve, size,
    },
    tables, titled,
};

/// The table parameter a gear's tooth count is chosen by.
pub const TEETH: &str = "teeth";

/// The most teeth a gear of the library has.
pub const MOST_TEETH: usize = 120;

/// The columns of the [`TEETH`] table: `z`, then the lower side of the gap
/// between two teeth, of module 1 (see [`involute::Gap`]): its foot `fx`,
/// `fy`, and the control points of its flank `c0x`, `c0y`, ...
const GAP_COLUMNS: [&str; 3 + 2 * (DEGREE + 1)] = [
    "z", "fx", "fy", "c0x", "c0y", "c1x", "c1y", "c2x", "c2y", "c3x", "c3y", "c4x", "c4y", "c5x",
    "c5y", "c6x", "c6y", "c7x", "c7y", "c8x", "c8y", "c9x", "c9y",
];

/// Every tooth count from [`FEWEST_TEETH`] to [`MOST_TEETH`], as the
/// table parameter [`TEETH`]: row `z20` the gap of a gear of 20 teeth.
fn teeth() -> GeopResult<Parameter> {
    let rows = (FEWEST_TEETH..=MOST_TEETH)
        .map(|z| {
            let gap = involute::gap(z)?;
            let mut values = vec![z as f64];
            values.extend(gap.foot);
            values.extend(gap.flank.iter().flatten());
            Ok(Row {
                name: format!("z{z}"),
                values,
            })
        })
        .collect::<GeopResult<_>>()?;
    Ok(Parameter {
        name: TEETH.into(),
        kind: ParameterKind::Table {
            columns: GAP_COLUMNS.iter().map(|c| c.to_string()).collect(),
            rows,
            selected: "z20".into(),
        },
    })
}

/// An involute spur gear, 20° pressure angle, of module `size.m` and
/// [`TEETH`]`.z` teeth, `width` wide up `z` from its side on the `xy`
/// plane, bored `bore` through: a disc of the tip diameter, the gap of
/// [`involute::gap`] patterned round it and cut away. Its datums: `axis`,
/// `side`, and the sketch `pitch`, its pitch circle on the side.
pub fn spur_gear(file: &'static str) -> GeopResult<StandardPart> {
    let mut program = family(
        "Steel",
        Some("#9aa0a8"),
        vec![
            size(tables::gear_modules()),
            teeth()?,
            Parameter::number("width", &format!("8 * {}", col("m")), 1.0, 100.0),
            Parameter::number(
                "bore",
                &format!("max(2, round({} * {TEETH}.z / 4))", col("m")),
                1.0,
                100.0,
            ),
        ],
    );
    let m = col("m");
    let z = format!("{TEETH}.z");
    // The disc's rim, a circle of the tip diameter: its quarters end on
    // multiples of 90°, tooth centres or at least 0.015 of a module from
    // where any gap of up to 120 teeth crosses the rim.
    let mut blank = Drawing::new(&program)?;
    let centre = blank.origin();
    blank.circle(centre, &format!("{m} * ({z} + 2)"))?;
    blank.circle(centre, "bore")?;
    extrude(
        &mut program,
        "blank",
        "blank_outline",
        (blank, outline_plane()),
        Extents::blind("width"),
        Combine::NewBody,
    );

    // One gap, round from its foot on the root circle: up its lower side,
    // over a point on `x` past the tip circle, down its upper side — the
    // lower one's mirror image — and back across the root. Extruded both
    // ways from the gear's middle, past both its sides.
    //
    // Only lines and the flanks, every point placed by a formula: a sketch
    // the solver places in one step for any size. With arcs, whose sweeps
    // it has to find, a gear far from the one drawn sent it off to
    // infinity. The root is so a chord of the root circle, at most
    // `r (1 - cos(π / 2z))` below it — 0.04 of a module for 12 teeth.
    let mut gap = Drawing::new(&program)?;
    let at = |column: &str, sign: &str| format!("{sign}{m} * {TEETH}.{column}");
    let lower =
        |d: &mut Drawing, k: &str| d.point(at(&format!("{k}x"), ""), at(&format!("{k}y"), ""));
    let upper =
        |d: &mut Drawing, k: &str| d.point(at(&format!("{k}x"), ""), at(&format!("{k}y"), "-"));
    let foot = lower(&mut gap, "f")?;
    let flank = (0..=DEGREE)
        .map(|k| lower(&mut gap, &format!("c{k}")))
        .collect::<GeopResult<Vec<_>>>()?;
    let upper_flank = (0..=DEGREE)
        .rev()
        .map(|k| upper(&mut gap, &format!("c{k}")))
        .collect::<GeopResult<Vec<_>>>()?;
    let upper_foot = upper(&mut gap, "f")?;
    gap.line(foot, flank[0]);
    gap.bezier(flank.clone());
    let past = gap.point(format!("{m} * ({z} / 2 + 2.5)"), "0")?;
    gap.line(flank[DEGREE], past);
    gap.line(past, upper_flank[0]);
    gap.bezier(upper_flank.clone());
    gap.line(upper_flank[DEGREE], upper_foot);
    gap.line(upper_foot, foot);
    plane_datum(&mut program, "middle", "width / 2");
    extrude(
        &mut program,
        "gap",
        "gap_outline",
        (gap, datum_plane("middle")),
        Extents {
            symmetric: true,
            ..Extents::blind(format!("width + 2 * {m}"))
        },
        Combine::NewBody,
    );
    program.push(
        "teeth",
        CircularPatternArgs {
            seeds: Seeds::bodies(vec![body("extrude(gap)")], Combine::cut("extrude(blank)")),
            axis: Some(TurnAxis::Datum(origin_axis(FrameAxis::Z))),
            reversed: false,
            count: z.as_str().into(),
            angle: Spacing::extent(360.0),
        },
    );

    let mut pitch = Drawing::new(&program)?;
    let centre = pitch.origin();
    pitch.circle(centre, &format!("{m} * {z}"))?;
    program.push("pitch", pitch.on(outline_plane()));
    axis_datum(&mut program);
    plane_datum(&mut program, "side", "0");
    Ok(StandardPart {
        file,
        base: "side",
        program: titled(
            program,
            "Involute spur gear, 20° pressure angle",
            "Spur gear",
        ),
        threaded: Vec::new(),
    })
}

/// The most teeth a rack of the library has.
pub const RACK_TEETH: usize = 30;

/// A gear rack of module `size.m`, `size.b` wide, its pitch line `size.h`
/// above its back, with `teeth` teeth — at most [`RACK_TEETH`] — running
/// `teeth · π m` along `z` from the `xy` plane: its teeth face `+y`, its
/// pitch plane is the `xz` plane, and it is centred on it across `x`. The
/// teeth are straight-sided, 20° to their centre lines, `π m / 2` thick on
/// the pitch line, the first centred half a pitch up from `z = 0`.
///
/// One profile of all [`RACK_TEETH`] teeth and half a gap at either end,
/// extruded across, then cut to length — through the middle of a gap — by
/// a box: a single boolean, where cutting a gap per tooth would split the
/// rack's long edges dozens of times over. Its datums: `axis`, the `z` axis
/// on the pitch plane — a slider joint's connector — `pitch`, `back`, and
/// `end`.
pub fn rack(file: &'static str) -> GeopResult<StandardPart> {
    let mut program = family(
        "Steel",
        Some("#9aa0a8"),
        vec![
            size(tables::racks()),
            Parameter::number("teeth", "20", 1.0, RACK_TEETH as f64),
        ],
    );
    let (m, b, h) = (col("m"), col("b"), col("h"));
    // In the profile plane: `x` up the teeth, along `y`; `y` along `z`.
    let half = |height: &str| format!("pi * {m} / 4 - {height} * tan(20)");
    let (root, tip) = (format!("-1.25 * {m}"), m.clone());
    let along = |k: usize, sign: &str, height: &str| {
        format!("{}.5 * pi * {m} {sign} ({})", k, half(height))
    };
    let mut corners = vec![
        [format!("-{h}"), "0".to_string()],
        [root.clone(), "0".into()],
    ];
    for k in 0..=RACK_TEETH {
        corners.push([root.clone(), along(k, "-", &root)]);
        corners.push([tip.clone(), along(k, "-", &tip)]);
        corners.push([tip.clone(), along(k, "+", &tip)]);
        corners.push([root.clone(), along(k, "+", &root)]);
    }
    let end = format!("{} * pi * {m}", RACK_TEETH + 1);
    corners.push([root.clone(), end.clone()]);
    corners.push([format!("-{h}"), end]);
    let mut profile = Drawing::new(&program)?;
    profile.polygon(&corners)?;
    let across = |length: String| Extents {
        symmetric: true,
        ..Extents::blind(length)
    };
    extrude(
        &mut program,
        "teeth",
        "profile",
        (profile, profile_plane()),
        across(b.clone()),
        Combine::NewBody,
    );
    let mut length = Drawing::new(&program)?;
    length.polygon(&[
        [format!("-{h} - {m}"), format!("-{m}")],
        [format!("2 * {m}"), format!("-{m}")],
        [format!("2 * {m}"), format!("teeth * pi * {m}")],
        [format!("-{h} - {m}"), format!("teeth * pi * {m}")],
    ])?;
    extrude(
        &mut program,
        "rack",
        "length",
        (length, profile_plane()),
        across(format!("{b} + 2 * {m}")),
        Combine::intersect("extrude(teeth)"),
    );
    axis_datum(&mut program);
    let xz = origin_plane(FrameAxis::Y);
    offset_datum(&mut program, "pitch", xz.name(), "0");
    offset_datum(&mut program, "back", xz.name(), &format!("-{h}"));
    plane_datum(&mut program, "end", "0");
    Ok(StandardPart {
        file,
        base: "back",
        program: titled(program, "Gear rack, 20° pressure angle", "Gear rack"),
        threaded: Vec::new(),
    })
}

/// The radius of a GT2 pulley's round groove, one per tooth of the belt.
const GT2_GROOVE: f64 = 0.555;

/// How deep a GT2 pulley's groove is, from its outside diameter.
const GT2_DEPTH: f64 = 0.76;

/// A GT2 timing pulley of `z` teeth for a 6 mm belt: a hub `dh` across and
/// `lh` long from its end on the `xy` plane, then the teeth `w` wide
/// between two flanges `df` across and `t` thick, bored `d` through — `d`,
/// `dh` and `lh` from its table, by bore.
///
/// The teeth are simplified: the outside diameter is the pitch diameter
/// `2z / π` less twice the belt's pitch line offset, 0.254, and a round
/// groove [`GT2_GROOVE`] in radius and [`GT2_DEPTH`] deep is cut for each
/// tooth of the belt. Their count fixes the outline, so each count is a
/// family: a ring of that outline, drawn in one sketch, joined to the hub
/// and flanges turned in one profile — one boolean. Its datums: `axis`,
/// `end`, and the plane `belt` through the middle of the belt, on which
/// the sketch `pitch` draws its pitch circle.
fn gt2_pulley(z: usize, file: &'static str) -> GeopResult<StandardPart> {
    let mut program = family(
        "Aluminium 6061",
        Some("#c8ccd2"),
        vec![size(tables::gt2_pulleys(z))],
    );
    let (d, dh, lh) = (col("d"), col("dh"), col("lh"));
    let (t, w) = (1.0, 7.0);
    let pitch = 2.0 * z as f64 / std::f64::consts::PI;
    let outside = (pitch - 0.508) / 2.0;
    let flange = format!("{}", outside + 2.0);
    let core = format!("{}", outside - 1.0);
    let (bore, hub) = (format!("{d} / 2"), format!("{dh} / 2"));
    let (inner_face, outer_face, end) = (
        format!("{lh} + {t}"),
        format!("{lh} + {}", t + w),
        format!("{lh} + {}", 2.0 * t + w),
    );
    let zero = || "0".to_string();
    let mut profile = Drawing::new(&program)?;
    profile.polygon(&[
        [bore.clone(), zero()],
        [hub.clone(), zero()],
        [hub, lh.clone()],
        [flange.clone(), lh.clone()],
        [flange.clone(), inner_face.clone()],
        [core.clone(), inner_face],
        [core, outer_face.clone()],
        [flange.clone(), outer_face],
        [flange, end.clone()],
        [bore, end],
    ])?;
    revolve(
        &mut program,
        "body",
        "profile",
        profile,
        Around::ZAxis,
        Combine::NewBody,
    );

    // The ring runs from the middle of one flange to the middle of the
    // other, so that none of its faces lies on one of theirs: round, per
    // tooth, a land on the outside circle and a groove, drawn as two arcs
    // meeting at its bottom so that each is less than half a circle.
    plane_datum(&mut program, "ring_floor", &format!("{lh} + {}", t / 2.0));
    let centre = outside - GT2_DEPTH + GT2_GROOVE;
    let half =
        ((outside.powi(2) + centre.powi(2) - GT2_GROOVE.powi(2)) / (2.0 * outside * centre)).acos();
    let mut ring = Drawing::new(&program)?;
    let at = |r: f64, a: f64| [format!("{}", r * a.cos()), format!("{}", r * a.sin())];
    let mut groove_ends = Vec::new();
    for k in 0..z {
        // Half a tooth round from `x`: no groove meets the seams of the
        // turned flanks, which lie on the axes.
        let a = 2.0 * std::f64::consts::PI * (k as f64 + 0.5) / z as f64;
        let [x0, y0] = at(outside, a - half);
        let [xb, yb] = at(outside - GT2_DEPTH, a);
        let [x1, y1] = at(outside, a + half);
        groove_ends.push([
            ring.point(x0, y0)?,
            ring.point(xb, yb)?,
            ring.point(x1, y1)?,
        ]);
    }
    let (groove, land) = (format!("{GT2_GROOVE}"), format!("{outside}"));
    for k in 0..z {
        let [start, bottom, end] = groove_ends[k];
        ring.arc(start, bottom, &groove, false)?;
        ring.arc(bottom, end, &groove, false)?;
        ring.arc(end, groove_ends[(k + 1) % z][0], &land, true)?;
    }
    let centre_point = ring.origin();
    ring.circle(centre_point, &format!("{}", 2.0 * (outside - 1.5)))?;
    extrude(
        &mut program,
        "ring",
        "ring_outline",
        (ring, datum_plane("ring_floor")),
        Extents::blind(t + w),
        Combine::join("revolve(body)"),
    );

    axis_datum(&mut program);
    plane_datum(&mut program, "end", "0");
    plane_datum(&mut program, "belt", &format!("{lh} + {}", t + w / 2.0));
    let mut circle = Drawing::new(&program)?;
    let centre_point = circle.origin();
    circle.circle(centre_point, &format!("{pitch}"))?;
    program.push("pitch", circle.on(datum_plane("belt")));
    Ok(StandardPart {
        file,
        base: "end",
        program: titled(program, "GT2 timing pulley, 6 mm belt", "GT2 pulley"),
        threaded: Vec::new(),
    })
}

pub fn gt2_pulley_16(file: &'static str) -> GeopResult<StandardPart> {
    gt2_pulley(16, file)
}

pub fn gt2_pulley_20(file: &'static str) -> GeopResult<StandardPart> {
    gt2_pulley(20, file)
}

pub fn gt2_pulley_36(file: &'static str) -> GeopResult<StandardPart> {
    gt2_pulley(36, file)
}

/// A shaft collar after DIN 705 A: a ring bored `d`, `D` across and `b`
/// wide, standing on the `xy` plane, with a set screw hole `ds` across
/// through its wall along `+x`, half way up: the thread's nominal
/// diameter. The boolean cutting it names the hole's faces after what it
/// crossed, so they are not listed as threaded.
pub fn shaft_collar(file: &'static str) -> GeopResult<StandardPart> {
    let mut program = family(
        "Steel",
        Some("#8e949c"),
        vec![size(tables::shaft_collars())],
    );
    let (d, big, b) = (col("d"), col("D"), col("b"));
    let mut profile = Drawing::new(&program)?;
    profile.polygon(&[
        [format!("{d} / 2"), "0".into()],
        [format!("{big} / 2"), "0".into()],
        [format!("{big} / 2"), b.clone()],
        [format!("{d} / 2"), b.clone()],
    ])?;
    revolve(
        &mut program,
        "ring",
        "profile",
        profile,
        Around::ZAxis,
        Combine::NewBody,
    );
    // Drawn in the profile plane, through the axis, and extruded out along
    // `+x` from inside the bore.
    let mut hole = Drawing::new(&program)?;
    let centre = hole.point("0", format!("{b} / 2"))?;
    hole.circle(centre, &col("ds"))?;
    extrude(
        &mut program,
        "set_screw",
        "set_screw_hole",
        (hole, profile_plane()),
        Extents {
            side1: Extent::ThroughAll,
            symmetric: false,
            side2: None,
            reversed: false,
        },
        Combine::cut("revolve(ring)"),
    );
    axis_datum(&mut program);
    plane_datum(&mut program, "base", "0");
    Ok(StandardPart {
        file,
        base: "base",
        program: titled(
            program,
            "Shaft collar with set screw, DIN 705 A",
            "DIN 705 A",
        ),
        threaded: Vec::new(),
    })
}

/// A rigid flange coupling as an envelope, joining a shaft `d1` across to
/// one `d2` across: two hubs `D` across, `L` long in all from its `d1` end
/// on the `xy` plane, and between them, in the middle, the bolted flanges
/// `F` across and `f` thick together. Its datums: `axis`, `end` — the `d1`
/// end — and `far_end`.
pub fn flange_coupling(file: &'static str) -> GeopResult<StandardPart> {
    let mut program = family(
        "Aluminium 6061",
        Some("#c8ccd2"),
        vec![size(tables::flange_couplings())],
    );
    let (d1, d2, big, flange, l, f) =
        (col("d1"), col("d2"), col("D"), col("F"), col("L"), col("f"));
    let (hub, rim) = (format!("{big} / 2"), format!("{flange} / 2"));
    let (low, mid, high) = (
        format!("({l} - {f}) / 2"),
        format!("{l} / 2"),
        format!("({l} + {f}) / 2"),
    );
    let mut profile = Drawing::new(&program)?;
    profile.polygon(&[
        [format!("{d1} / 2"), "0".into()],
        [hub.clone(), "0".into()],
        [hub.clone(), low.clone()],
        [rim.clone(), low],
        [rim, high.clone()],
        [hub.clone(), high],
        [hub, l.clone()],
        [format!("{d2} / 2"), l.clone()],
        [format!("{d2} / 2"), mid.clone()],
        [format!("{d1} / 2"), mid],
    ])?;
    revolve(
        &mut program,
        "coupling",
        "profile",
        profile,
        Around::ZAxis,
        Combine::NewBody,
    );
    axis_datum(&mut program);
    plane_datum(&mut program, "end", "0");
    plane_datum(&mut program, "far_end", &l);
    Ok(StandardPart {
        file,
        base: "end",
        program: titled(program, "Rigid flange shaft coupling", "Flange coupling"),
        threaded: Vec::new(),
    })
}