Positioning¶

The Position class is how llmcad handles 3D coordinates without requiring LLMs to do 3D math. Positions are always relative to a face, using face-local offsets.

Position¶

A Position is a 3D point that optionally knows which face it belongs to.

pos = box.top.center  # Position on the top face
print(pos)            # Position(0.00, 0.00, 5.00, face=top)

Properties¶

pos.x    # global X coordinate
pos.y    # global Y coordinate
pos.z    # global Z coordinate
pos.vec  # underlying Vec3

Face-local offsets¶

The key feature of Position is offset(). When a position is associated with a face, offsets are in face-local coordinates:

pos.offset(dx=10)          # 10mm to the right on the face
pos.offset(dy=5)           # 5mm upward on the face
pos.offset(dz=3)           # 3mm along the face normal (outward)
pos.offset(dx=10, dy=-5)   # right and down

How face-local coordinates work¶

Each face has its own 2D coordinate system:

dx moves along the face's x_dir ("rightward")
dy moves along the face's y_dir ("upward")
dz moves along the face's normal ("outward")

For a top face (normal = +Z):

dx → +X (rightward)
dy → +Y (backward)

For a front face (normal = -Y):

dx → +X (rightward)
dy → +Z (upward)

This means the same code offset(dx=10) always means "move right on this face," regardless of whether it's the top, front, or any other face.

Example¶

from llmcad import Box, Circle, extrude

plate = Box(100, 60, 10)

# Place holes at specific offsets from center
for dx in [-20, 0, 20]:
    pos = plate.top.center.offset(dx=dx)
    hole = extrude(Circle(8).place_on(plate.top, at=pos), through=True)
    plate = plate - hole

Corner inset¶

.inset() moves from a corner position toward the face center. The direction is automatic --- you don't need to think about signs.

pos = face.corners.TL.inset(dx=10, dy=10)  # 10mm inward from top-left
pos = face.corners.BR.inset(dx=8, dy=8)    # 8mm inward from bottom-right

This is the recommended way to place features near corners:

plate = Box(100, 60, 10)

# Mounting holes in all four corners
for corner in plate.top.corners:
    pos = corner.inset(dx=8, dy=8)
    hole = extrude(Circle(5).place_on(plate.top, at=pos), through=True)
    plate = plate - hole

Projection¶

Project a position onto another face's plane:

# Project a point from the top face onto the front face
pos_on_front = pos_on_top.projected_onto(plate.front)

Distance¶

Measure the distance between two positions:

d = pos_a.distance_to(pos_b)  # Euclidean distance in mm

Or use the measure() debug function:

from llmcad import measure
measure(plate.top.center, plate.bottom.center)  # prints: Distance: 10.000 mm

Global positions¶

If a position has no associated face, offset() works in global XYZ:

from llmcad import Position
from llmcad._vec import Vec3

pos = Position(Vec3(10, 20, 30))
moved = pos.offset(dx=5, dy=0, dz=10)  # global offset: (15, 20, 40)