Table of Contents

Class GeneralXyzabcMachineTool

Namespace
Hi.NcMech.Xyzabc
Assembly
HiMech.dll

An XYZABC machine tool: a mechanism that owns its key assembly, its root anchor and the solids hung on its anchors, and names which of its own elements play the machine's roles — the table and tool mount anchors (TableMount, ToolMount) and the six axis branches (AxisX … AxisC). The axis and mount transformers are the ones on those branches; the transformer properties only delegate to them.

The roles are the user's to set: each is a property taking any anchor (a mount) or inner branch (an axis) of the machine's own assembly, or null to unbind. A machine built from chain code, adopted from a topology or read from a legacy file resolves them by name: the direct child anchors w and t, and the branches X,Y,Z,A,B,C (for a mount the first anchor of that name, for an axis the last branch). When no element carries the exact name, the one element whose name matches ignoring letter case is bound, with a message; several such elements bind none, with a message; a mount nothing matches stays unbound, with a message, and the machine still loads.

The spindle (Spindle) is a ninth role, found by topology rather than by name: the branch arriving at the anchor the tool mount hangs from (S in [B][S][t]), taken only when it carries a DynamicRotation whose axis runs along the tool mount's Z axis (IsSpindleOnToolAxis()) and it plays no axis role. A machine whose spindle branch carries anything else — the NoTransform most machines were built with, a gauge-line StaticTranslation — leaves the role unbound and plays as it always did; a rotation off the tool axis is reported and left unbound too, as turning it would swing the tool around.

Reading takes, in this order, the embedded topology (<Asmb>, <Root>, <AnchorToSolid>, see MechanismXml), a legacy <GeneralMechanism> (inline or a side file), the legacy <XyzabcChain> wrapper (a mechanism-backed or a chain-code chain, inline or a side file), or a bare <ChainCode>. Writing always embeds the topology in one MechanismXml section; there is no separate element for any transformer. The nine roles are written next to it, each under its own element name (<TableMount>, <ToolMount>, <AxisX> … <AxisC>, <Spindle>) naming the element by Guid, an unbound role as an empty element. On reading an embedded file, a role element naming an element by Guid binds it (a Guid the topology lacks leaves the role unbound, with a message; a spindle off the tool axis is bound as recorded, with a message); a role element absent — a file written before the roles were persisted — falls back to the name convention above (the topology rule for the spindle), and so does an empty mount element (nothing was bound when the file was written, a state no machine runs in); an empty axis or spindle element leaves the role unbound silently, so a role unbound on purpose stays so even when a branch carries its letter.

public class GeneralXyzabcMachineTool : IXyzabcMachineTool, IMachiningChain, IMechanism, ITopo, IGetAsmb, IGetAnchor, IGetTopoIndex, IGetAnchoredDisplayeeList, IGetAnchorToSolidDictionary, IMakeXmlSource, IXyzabcAxes, IDisplayee, IExpandToBox3d, INameNote, IGetCollisionIndexPairs
Inheritance
GeneralXyzabcMachineTool
Implements
Inherited Members
Extension Methods

Constructors

GeneralXyzabcMachineTool()

Initializes an empty machine: an assembly named DefaultAsmbName holding only the root anchor O, no solids, no role bound. Build the topology on it, or start from CreateFromChainCode(string).

public GeneralXyzabcMachineTool()

GeneralXyzabcMachineTool(Asmb, Anchor, Dictionary<Anchor, Solid>, IProgress<IMessage>)

Initializes a machine adopting an existing topology — the instances as they are — and resolves its roles by name, reporting what the name convention finds to progress.

public GeneralXyzabcMachineTool(Asmb asmb, Anchor root, Dictionary<Anchor, Solid> anchorToSolid, IProgress<IMessage> progress = null)

Parameters

asmb Asmb

The key assembly.

root Anchor

The root anchor, inside asmb.

anchorToSolid Dictionary<Anchor, Solid>

The solid dictionary, keyed by anchors of asmb; kept as the live instance.

progress IProgress<IMessage>

Progress reporter for the role-resolution diagnostics (a mount unbound or matched ignoring letter case, an ambiguous name); null discards them.

Exceptions

ArgumentNullException

Any member is null.

ArgumentException

The root anchor is not inside the assembly.

GeneralXyzabcMachineTool(XElement, string, IProgress<IMessage>)

Initializes a new instance of the GeneralXyzabcMachineTool class from XML.

public GeneralXyzabcMachineTool(XElement src, string baseDirectory, IProgress<IMessage> progress)

Parameters

src XElement

XML element source.

baseDirectory string

Base directory.

progress IProgress<IMessage>

Progress reporter for the diagnostics emitted while the topology, the roles and the collision pairs load.

Fields

DefaultAsmbName

The name of the key assembly of a machine created by GeneralXyzabcMachineTool() or CreateFromChainCode(string).

public const string DefaultAsmbName = "GeneralXyzabcMachineTool"

Field Value

string

XName

Name of XML element.

public static string XName

Field Value

string

Properties

AnchorToSolid

The solids hung on the machine's anchors; the live instance, edited in place.

public Dictionary<Anchor, Solid> AnchorToSolid { get; }

Property Value

Dictionary<Anchor, Solid>

Asmb

The key assembly holding every anchor and branch of the machine.

public Asmb Asmb { get; }

Property Value

Asmb

AxisA

The branch driven as the A axis; null when the machine has none. As AxisX; TransformerA is null unless the branch carries a rotation.

public Branch AxisA { get; set; }

Property Value

Branch

Exceptions

ArgumentException

The branch is not inside Asmb.

AxisB

The branch driven as the B axis; null when the machine has none. As AxisA.

public Branch AxisB { get; set; }

Property Value

Branch

Exceptions

ArgumentException

The branch is not inside Asmb.

AxisC

The branch driven as the C axis; null when the machine has none. As AxisA.

public Branch AxisC { get; set; }

Property Value

Branch

Exceptions

ArgumentException

The branch is not inside Asmb.

AxisX

The branch driven as the X axis; null when the machine has none. Assign any inner branch of Asmb, or null to unbind; TransformerX reads the branch's transformer from then on (null unless it is a translation).

public Branch AxisX { get; set; }

Property Value

Branch

Exceptions

ArgumentException

The branch is not inside Asmb.

AxisY

The branch driven as the Y axis; null when the machine has none. As AxisX.

public Branch AxisY { get; set; }

Property Value

Branch

Exceptions

ArgumentException

The branch is not inside Asmb.

AxisZ

The branch driven as the Z axis; null when the machine has none. As AxisX.

public Branch AxisZ { get; set; }

Property Value

Branch

Exceptions

ArgumentException

The branch is not inside Asmb.

ChainCode

The semicolon-joined form of ChainCodes.

public string ChainCode { get; }

Property Value

string

ChainCodes

The chain code segments of the machine's topology (DeriveChainCodes(IMechanism): the table-mount limb first, then the tool-mount one, then any others). Assigning reseeds the topology under the XYZABC conventions, carrying the transformers (each with the error-term mark of its branch) and solids of same-named components over, and resolves the roles again.

public IReadOnlyList<string> ChainCodes { get; set; }

Property Value

IReadOnlyList<string>

Exceptions

InvalidOperationException

Assigned while the machine is mounted in an equipment (a branch leaves its assembly); detach it first.

ArgumentException

The assigned code is invalid.

CodeToAnc

The component words of the machine mapped to their anchors (CodeToAnc(IMechanism)).

public Dictionary<string, Anchor> CodeToAnc { get; }

Property Value

Dictionary<string, Anchor>

CollisionIndexPairs

Collection of collision index pairs for collision detection.

public HashSet<CollisionIndexPair> CollisionIndexPairs { get; }

Property Value

HashSet<CollisionIndexPair>

EnableAutoGeneratingCollisionIndexPairsOnXmlLoaded

Gets or sets whether to automatically generate collision index pairs when loaded from XML.

public bool EnableAutoGeneratingCollisionIndexPairsOnXmlLoaded { get; set; }

Property Value

bool

McCodes

Gets the machine coordinate code sequence for decoding the MC array.

public string[] McCodes { get; }

Property Value

string[]

McTransformers

The six axis transformers in McCodes order, null for an absent axis — computed from the axis branches on every read, so they are always the instances on the branches.

public IDynamicRegular[] McTransformers { get; }

Property Value

IDynamicRegular[]

Name

Gets or sets the name of the object.

public string Name { get; set; }

Property Value

string

Note

Gets or sets the descriptive note for the object.

public string Note { get; set; }

Property Value

string

Root

The root anchor the kinematics are measured from.

public Anchor Root { get; }

Property Value

Anchor

Spindle

The branch driven as the spindle's turn — on a chain-code machine the one arriving at S, the anchor the tool mount hangs from; null when the machine has none. Assign any inner branch of Asmb, or null to unbind; SpindleTransformer reads the branch's transformer from then on (null unless it is a rotation).

The spindle angle is not a machine coordinate: it is not among McCodes, playback writes it while the spindle stands (M05, an oriented stop) and holds it while the spindle turns, and the kinematics solver reads it as 0°. For the tool to turn in place, the rotation's axis runs along the tool mount's Z axis through its origin (IsSpindleOnToolAxis()): its Pivot is the tool mount's origin and its Axis the tool mount's −Z, so a positive angle turns the M03 (clockwise) way seen from the spindle toward the tool tip.

public Branch Spindle { get; set; }

Property Value

Branch

Exceptions

ArgumentException

The branch is not inside Asmb.

SpindleTransformer

The spindle transformer: the one on Spindle, null when that is absent or not a rotation.

public DynamicRotation SpindleTransformer { get; }

Property Value

DynamicRotation

TableMount

The anchor the fixture or workpiece is attached to (the w end); null when unbound. Assign any anchor of Asmb to make it the table end, or null to unbind, at any point of building the topology; an equipment the machine is mounted in moves its attachment on Rewire(). The setter checks one thing only — the anchor is the machine's own; whether the machine is complete (both ends bound, reached by the root) is judged where it matters (RequireEndAnchors(IXyzabcMachineTool) at the run start, the web editor's checks), not here.

public Anchor TableMount { get; set; }

Property Value

Anchor

Exceptions

ArgumentException

The anchor is not inside Asmb.

TableMountTransformer

The static transformer on the unique branch arriving at the table mount; null when there is no such branch. Assigning replaces the transformer on that branch.

public IStaticTransformer TableMountTransformer { get; set; }

Property Value

IStaticTransformer

Exceptions

InvalidOperationException

Assigned while no unique branch arrives at the table mount.

ToolMount

The anchor the tool is attached to (the t end); null when unbound. As TableMount.

public Anchor ToolMount { get; set; }

Property Value

Anchor

Exceptions

ArgumentException

The anchor is not inside Asmb.

ToolMountTransformer

The static transformer on the unique branch arriving at the tool mount; null when there is no such branch. Assigning replaces the transformer on that branch.

public IStaticTransformer ToolMountTransformer { get; set; }

Property Value

IStaticTransformer

Exceptions

InvalidOperationException

Assigned while no unique branch arrives at the tool mount.

TransformerA

The A-axis transformer: the one on AxisA, null when that is absent or not a rotation.

public DynamicRotation TransformerA { get; }

Property Value

DynamicRotation

TransformerB

The B-axis transformer: the one on AxisB, null when that is absent or not a rotation.

public DynamicRotation TransformerB { get; }

Property Value

DynamicRotation

TransformerC

The C-axis transformer: the one on AxisC, null when that is absent or not a rotation.

public DynamicRotation TransformerC { get; }

Property Value

DynamicRotation

TransformerX

The X-axis transformer: the one on AxisX, null when that is absent or not a translation.

public DynamicTranslation TransformerX { get; }

Property Value

DynamicTranslation

TransformerY

The Y-axis transformer: the one on AxisY, null when that is absent or not a translation.

public DynamicTranslation TransformerY { get; }

Property Value

DynamicTranslation

TransformerZ

The Z-axis transformer: the one on AxisZ, null when that is absent or not a translation.

public DynamicTranslation TransformerZ { get; }

Property Value

DynamicTranslation

Methods

CreateFromChainCode(string)

Creates a machine from chain code under the XYZABC conventions (XyzabcChainCodeConvention): the mounts w and t are required, the axis branches get the default transformers.

public static GeneralXyzabcMachineTool CreateFromChainCode(string chainCode = "[O][Z][C][w];[O][Y][X][B][S][t]")

Parameters

chainCode string

Semicolon-separated branch segments; see ChainCodeUtil.

Returns

GeneralXyzabcMachineTool

The new machine; its assembly is named DefaultAsmbName.

Exceptions

ArgumentException

The code is empty, malformed, disconnected, or lacks a mount.

Display(Bind)

Display function called in DispEngine rendering loop.

public void Display(Bind bind)

Parameters

bind Bind

Bind with DispEngine. See Bind.

ExpandToBox3d(ref box3d_t)

Expands dst over the anchors and the solids — the anchors too, so a machine without solids still has an extent.

public void ExpandToBox3d(ref box3d_t dst)

Parameters

dst box3d_t

The box to expand.

FromLegacyChainElement(XElement, string, string, IProgress<IMessage>)

Reads a legacy chain element — the retired <GeneralXyzabcChain> (its mechanism inline or in a side file), <CodeXyzabcChain> or its <XyzabcChain> alias — as a machine with no name and no collision pairs (an explicit empty list, as the retired chain carried none), its roles resolved by name.

public static GeneralXyzabcMachineTool FromLegacyChainElement(XElement src, string baseDirectory, string relFile, IProgress<IMessage> progress)

Parameters

src XElement

The chain element.

baseDirectory string

The base directory for relative paths.

relFile string

The chain's side file relative to baseDirectory, or null when inline.

progress IProgress<IMessage>

Progress reporter for the load diagnostics.

Returns

GeneralXyzabcMachineTool

The machine.

GenerateCollisionIndexPairs()

Regenerates CollisionIndexPairs from the topology.

public void GenerateCollisionIndexPairs()

Exceptions

InvalidOperationException

A mount is unbound.

GetAnchor()

Get key anchor. (i.e. root anchor)

public Anchor GetAnchor()

Returns

Anchor

key anchor

GetAnchorToSolidDictionary()

Gets a dictionary that maps Anchor objects to their corresponding Solid objects.

public Dictionary<Anchor, Solid> GetAnchorToSolidDictionary()

Returns

Dictionary<Anchor, Solid>

A dictionary where keys are anchors and values are their associated solids.

GetAnchoredDisplayeeList()

The solids only, each seeded with its anchor's Guid color when it has no authored color; a persisted entry without a solid is skipped.

public List<IAnchoredDisplayee> GetAnchoredDisplayeeList()

Returns

List<IAnchoredDisplayee>

The anchored solids.

GetAsmb()

Gets the key asmb.

public Asmb GetAsmb()

Returns

Asmb

The key asmb.

GetCollisionIndexPairs()

Gets a collection of collision index pairs for collision detection.

public IEnumerable<CollisionIndexPair> GetCollisionIndexPairs()

Returns

IEnumerable<CollisionIndexPair>

A collection of CollisionIndexPair objects.

GetSpindleTransformer()

The rotation that turns the tool about its own axis — the spindle's angle, positive the M03 (clockwise) way; null when the machine has none. Not among the machine coordinates of IXyzabcAxes: playback writes it while the spindle stands, and the kinematics solver reads it as 0°.

public DynamicRotation GetSpindleTransformer()

Returns

DynamicRotation

The spindle's rotation, or null.

GetTableMount()

Gets the table mount anchor point.

public IGetAnchor GetTableMount()

Returns

IGetAnchor

The table mount anchor point.

GetToolMount()

Gets the tool mount anchor point.

public IGetAnchor GetToolMount()

Returns

IGetAnchor

The tool mount anchor point.

GetTransformerA()

Get transformer A.

public DynamicRotation GetTransformerA()

Returns

DynamicRotation

transformer A

GetTransformerB()

Get transformer B.

public DynamicRotation GetTransformerB()

Returns

DynamicRotation

transformer B

GetTransformerC()

Get transformer C.

public DynamicRotation GetTransformerC()

Returns

DynamicRotation

transformer C

GetTransformerX()

Get transformer X.

public DynamicTranslation GetTransformerX()

Returns

DynamicTranslation

transformer X

GetTransformerY()

Get transformer Y.

public DynamicTranslation GetTransformerY()

Returns

DynamicTranslation

transformer Y

GetTransformerZ()

Get transformer Z.

public DynamicTranslation GetTransformerZ()

Returns

DynamicTranslation

transformer Z

IsSpindleOnToolAxis()

Whether turning SpindleTransformer leaves the tool in place: its axis runs along the tool mount's Z axis, either sense, and passes through the tool mount's origin (within 1e-3 mm and 1e-6 rad). Then the tool mount's origin and Z axis — the tool's point and direction, the cutter location — stay where they are at any spindle angle, and only the tool's own turn about Z changes. False when the spindle is unbound or not a rotation, the tool mount is unbound, or the spindle branch does not reach the tool mount.

public bool IsSpindleOnToolAxis()

Returns

bool

Whether the spindle turns about the tool axis.

MakeXmlSource(string, string, bool)

Writes <Name>, <Note>, the topology in one MechanismXml section (every transformer inside its branch), the nine roles — each under its own element name, by Guid, an unbound role as an empty element — and <CollisionIndexPairs>.

public XElement MakeXmlSource(string baseDirectory, string relFile, bool exhibitionOnly)

Parameters

baseDirectory string

The base directory for resolving relative paths

relFile string

The relative file path for the XML source

exhibitionOnly bool

if true, the extended file creation is suppressed.

Returns

XElement

An XML element representing the object's state

Remarks

For the demand of easy moving source folder (especially project folder) without configuration file path corruption, the relative file path is applied. The baseDirectory is typically the folder at the nearest configuration file folder. Since the folder can be moving with the configuration file.

Reg(XFactory)

Registers this type's deserializer with the given XFactory and chains Reg(factory) on dependents. Idempotent.

public static void Reg(XFactory factory = null)

Parameters

factory XFactory