Knowledge Bridge Documentation

Help version: 3.3.8

 

Overview

A Model’s position is the combination of its location and orientation.  In KB, this is captured into a data type called a Frame.  Frames are defined mathematically using a 4x3 matrix of numeric values in a form that is standard in the computer graphics world.  

A Frame can be considered a kind of local coordinate system.  In kBridge, one never has to deal with the individual values (except possibly in an import or export situation when data is being transferred).  Instead, various functions and Rules are used to create Frames, "match" Frames. These functions and Rules combine them and extract out various aspects, like the origin.

A Frame can be considered a kind of local coordinate system.  In kB, one never has to deal with the individual values (except possibly in an import or export situation when data is being transferred).  Instead, various functions and Rules are used to create Frames, "match" Frames. These functions and Rules combine them and extract out various aspects, like the origin.

The position Rule is one such case.  There are currently 4 ways to position Models in KB.  More will be added in the future.  All of these methods use a "position specification" object, which is just a JavaScript object containing name-value pairs.   These name-value pairs are not required to appear in any particular order, and a few are entirely optional. See the tables below for required and optional values, where optional values are those listed as required = no.

The value of a position rule must be a position specification object.  It is only a specification; these can be shared between Designs, passed around like any other values, referenced, pulled out of arrays, and so on.  Their only purpose in life is to be fed to the computeFrame function to create a Frame.

Each position specification has a required property called type, which is placed first by convention.  This is the specification type and has a string value.

The specifics of each specification type are defined below.

Position Specification Types

Match

A match spec is the simplest specification.  It takes a single Frame and produces that exact Frame when processed.

 

Origin

This uses the makeFrame function internally to produce a Frame.

You can safely assume that xdir will exactly match the x-direction of the resulting Frame, but you cannot make that assumption for ydir and the y-direction.  The z-direction is computed from the cross product ydir X xdir.

Constraints

For more details, see the full section on the Constraints specification.

 

Connection

For more details, see the full section on Connectors.

 

Constraints

A Constraints specification allows the application of successive geometric position constraints on a Frame to lock it into place.  The constraints use named box faces, offsets and mate directions to restrict the Frame into lower and lower degrees of freedom until no more can be applied.  If the number of constraints is lower than needed to fully lock the Frame into place, then it possesses the ability to move under certain circumstances.

Box Face constraints are not restricted to Blocks, and multiple constraints are not limited to orthogonal directions; they just use a "virtual box" as supplied by BoxMixin, to define directions and faces.  You can therefore place invisible blocks in your assembly and constrain to them.  Note that several primitive objects include BoxMixin, so you can constrain to them as if they were a Block.

Box Face Naming

Box faces are named specifically and deliberately in KB.  

Front,the -Y face

Back,the +Y face

Left,the -X face

Right,the +X face

Up,the +Z face

Down,the -Z face

Each face name starts with a unique letter, so that combinations of faces are unambiguous. Thus, the rules defining corners are named as vertexLFU.  When used like this, the ordering is always using XYZ; the x-face comes first, followed by the y face, and then z. Face centers fully spell out the face, such as faceCenterUp, and edge centers abbreviate, such as edgeCenterFU.

A single Box Face constraint defines the face on the object being constrained to (the "reference" object) and the face on the object being constrained ("my" object from the point of view of the constraint), and optionally offset distance between the faces can be set, as well as orientation, with face normals parallel (flush) or anti-parallel (mate).

To put the Down face of a box-based "table.top" onto the Up face of a table, we would write the constraint as

{refface: "Up", refbox: root.table.top, myface: "Down"}

 

The offset is zero by default, so it is not needed.  The mate is also the default, so it is not needed.

The above constraint removes only a few degrees of freedom. The box can still meet the constraint anywhere on (or even off) the table, and it can spin around the Z-axis.  These will default to something as close to the parent’s orientation as possible. For example, the box will end up at the center of the table, and it will stick there, even if the table is titled or moved, because the constraint is to the table top, and not the world.

Each constraint can have its own refbox. We can constrain another side to the table top side, or to another box on the table. These remove more degrees of freedom. Three constraints are usually sufficient to completely lock down an object, but if the constraints are not really independent, they will be ignored. For example, we cannot constraint both the Up and Down of the box to the table top Up face. The first constraint to lock down a particular degree of freedom wins, and constraints are always applied in the order provided in the constraints array.

Connectors

Connections are component-to-component constraints that allow "snapping" and other detection and matching feedback in the interactive graphic environment.  A Connector is effectively a "half connection", defining one side of a two-way match.  For each component, there must be a Connector defined to support one side of a connection of a given connection type.  A connection type is a simple string name.  There is no limit to the number of connection types, and the content of the string is not restricted except that it must not contain whitespace or double or single quotes.

A Connector is an object, with the following properties:

connector => { name: string, frameName: string, keys: keypair[] }

keypair => { key: string, polarity: integer }

 

The name of the connector is primarily for human reference, and should be unique from all other connectors in a given component.  Consider it to be the name of the "place" where the connection will happen.

The frameName is the rule name of the relative Frame from the transform Frame of the local object.  It should define the position of the connector, and it must be a relative Frame, not dependent on the transform Frame, because it is used to define that Frame.  Failure to use a relative Frame will result in circular reference errors.  See the subsection on Defining Relative Frames.

The keys are an array of keypair objects.  There must be at least 1 such pair, and there is no limit to how many can be present.  The keypairs are the heart of the matching ability of connectors.  Two connectors match when:

1.They are not already matched.

2.They are not on the same object.

3.They have the same key.

4.Their polarities sum to 0.