Ring dimensions

from ArtisanPlugin.Scripting import DraftingApi as drafting

The measurements a bench worker asks for on a ring drawing: how wide the finger hole is, how thick and how wide the shank is under the finger, how tall and how wide the design sits above it, and how broad the band is seen from above. It is the ArtisanGenerateDimensionsFromRing command run headless — the command takes no input, so neither does this method.

Usage

ok = drafting.GenerateDimensionsFromRing()

There are no parameters. The gap between the geometry and the dimension lines is fixed at 2 mm, and the ring is expected in the standard Artisan orientation: the finger hole centred on the world origin, the design pointing up the Z axis.

What it draws

Every object in the document — not a selection — is meshed together at low resolution, and six linear dimensions are placed on it:

Annotation	Measures
Finger size	The full finger diameter across the bore, taken from the parametric ring’s own finger size, not from the mesh
Bottom (2)	The shank’s thickness in Z below the finger hole, and its width in Y at that height, both from the section through the world YZ plane
Top (2)	The width in Y at finger-radius height, and the height from the finger radius up to the top of the model
Size	The shank section’s extent in X on the positive-X side, from the section through the world XY plane

The old single-page reference described this as “bottom, top and size annotations”. That is three of the four groups: the finger-diameter dimension is the fourth, and the bottom and top groups are two dimensions each rather than one.

The dimension style and the layer

Two side effects distinguish this method from the generic Auto-dimensions:

• The current dimension style is halved and saved back to the document — text height, arrow size and the rest of its length values are scaled by 0.5 so the annotations read at ring scale. The change persists, and it is not idempotent: calling the method twice halves the style twice, three times halves it again. If a script dimensions several rings in a session, reset the style between runs or expect the text to shrink each time.
• The annotations avoid the metal layer. Attributes are built from the document defaults, and if the current layer’s name contains Metal the dimensions are diverted to the layer named Default instead. On any other current layer they land there, exactly as the generic method’s do.

The analysis mesh is also nudged by 0.001 mm on each axis before it is measured, so a face lying exactly on a section plane still produces a section.

It is not ring-only

Despite the name, this method runs the same design-type branch the generic entry point does. If the document’s design type is not RING, it draws the three bounding-box dimensions — width in X, depth in Y, height in Z — instead of the ring set, after having halved the dimension style. Set the design type before calling it, or use Box dimensions if a bounding box is what you actually want.

The return value

The method returns a bool: True when the command reported success, False when it failed. It fails when:

• The licence check did not pass.
• The document’s objects could not be meshed at low resolution. The command shows a modal “Unable to generate dimensions” dialog first, which will block an unattended script.
• The design type is RING but no parametric ring is present. The finger diameter is read from the first Cathedral, Classic, Signet, curve-driven or Advanced ring object found in the document; a ring modelled as plain breps carries no finger size, so the command returns failure with nothing added and no message on the command line. DocumentApi’s ring size reads the same parametric value — check it first if you are unsure.

Note that the dimension-style change happens before those last two checks, so a False can still leave the style halved.

Wrap the call in a Transaction so all six annotations undo together.

from ArtisanPlugin.Scripting import DraftingApi as drafting, Transaction

with Transaction.Begin("Ring dimensions"):
    if not drafting.GenerateDimensionsFromRing():
        print("No parametric ring to dimension.")