R | K4 docs

The object R ("big R") is available in all Rules and Methods as a holder of most rule utility methods. It has several properties which hold topic-specific utilities:

geom: Holds geometric utilities
model: Holds model utilities
reflect: Holds reflection methods
message: Holds messaging methods

To see these methods, click on the property, and then click on the sub-object type, such as RGeom under R.geom.

Hierarchy

Index

Properties

Accessors

Methods

Properties

Readonly demandChildren

demandChildren: function

Evaluate children.

param: Child rule.
param: Optional. If set to 'true', errors during the child demand are ignored.
returns: Array with the evaluated children.

geom

geom: RGeom

SubObject with geometry methods

Readonly loadFile

loadFile: function

a) Provide access to resource file. This is used when the resource needs to be accessed as a file, such as an SQLite database or Excel file. Use getUrl when the resource needs to be accessed via a URL, such as STL and Textures. b) Download an URL to local file.

param: Resource ID or URL of file to download.
returns: Local pathname of the resource file or the downloaded file.

message

message: Message

Object to post messages

model

model: RModel

SubObject with model methods

nullHandle

nullHandle: string = "0|0"

Handle for non-existant objects

Readonly ref

ref: function

Evaluate refchain, or model and ruleName. The following all return the same value, assuming the current root name is 'Table1':

"root.leg.height" // root converted to current root
"world.root.leg.height" // root converted to current root
"world.Table1.leg.height" // no conversion
"world.TableFromBefore.leg.height" // converted to current root
"Table1.leg.height" // world prepended
"leg.height" // world.Table1 prepended

param: Either a model or a string refChain
param: Optional. If present, the first argument must be a model
example: R.ref('world.rootname.foo') or R.ref(<root>, 'foo')

reflect

reflect: Reflect

SubObject with reflection methods

Readonly typeCheck

typeCheck: function

Performs a typeCheck operation.

param: The value to test
param: The strng name for the type
param: optional The name of the value. Supply this to throw an exception when the type check fails.

Readonly update

update: function

Performs the update operation on model

param: The model whose Update rules should be evaluated

Accessors

rootModel

rootModel:

Root model.

settings

settings:

Get settings POJO. NOTE: pretty cheap operation. No need to cache.

symbols

symbols:

Internal K4 symbols. Used to reference protected properties of Designs and Models. These are case-sensitive. You must use object[] notation. Currently supported:

design
designName
index
name
params
parent
refChain

example: this[R.symbols.designName]

version

version:

K4 kernel version.

world

world:

World model.

Methods

AAA

AAA(axis: Vector): Vector

Aribitrary Axis Algorithm: Given a vector, produces an orthogonal vector in a repeatable way. See AAA.
example
```
 R.AAA(this.unitZ) => v<1,0,0>
```
Parameters
- axis: Vector
  
  The vector you want a vector perpendicular to.
Returns Vector

A unit vector perpendicular to axis

acos

acos(x: number): number

Returns the inverse cosine in degrees.

Parameters
- x: number
  
  The value
Returns number

asin

asin(x: number): number

Returns the inverse sine in degrees.

Parameters
- x: number
  
  The value
Returns number

asleep

asleep(model: Instance): boolean

Determines if not all Required params are supplied

Parameters
- model: Instance
  
  Model to check on
Returns boolean

atan

atan(ratio: number): number

Returns the arc tangent in degrees.

Parameters
- ratio: number
  
  The rise/run value
Returns number

atan2

atan2(y: number, x: number): number

Returns the signed arc tangent in degrees.

Parameters
- y: number
  
  The rise
- x: number
  
  The run
Returns number

computeTransform

computeTransform(fromFrame: Frame, toFrame: Frame): Frame

Computes the transform to get from fromFrame to toFrame. In matrix terms, computes M such that fromFrame X M => toFrame

Parameters
- fromFrame: Frame
  
  Reference frame
- toFrame: Frame
  
  Target frame
Returns Frame

cos

cos(deg: number): number

Returns the cosine of the angle.

Parameters
- deg: number
  
  The angle in degrees.
Returns number

degrees

degrees(radians: number): number

Convert radians to degrees.

Parameters
- radians: number
  
  Radians
Returns number

Degrees

error

error(message: string): never

Deliberately throw an error.

Parameters
- message: string
  
  Error message
Returns never

gencat

gencat(a: string | [], b: string | []): any

This concatenates a pair of strings, or a pair of arrays. This function should not be used in new code. It is intended to support translated source from earlier systems.

Parameters
- a: string | []
  
  A string or array argument
- b: string | []
  
  A string or array argument
Returns any

getAllRules

getAllRules(model: Instance): RuleDescriptor[]

Returns a set of RuleDescriptors for all rules on model.

Parameters
- model: Instance
  
  The instance
Returns RuleDescriptor[]

getModelJson

getModelJson(model: Instance, name?: string): string

Returns the model definition for the given model as a JSON string.

Parameters
- model: Instance
  
  The model to get the definition for.
- Optional name: string
  
  Optional. Gives the result the name given, instead of its current name.
Returns string

A string. Use JSON.parse() to create the JS object.

getOutputDir

getOutputDir(): string

Creates dir to use for outputs generation.

Returns string

The dir name.

getOutputFile

getOutputFile(desiredFilename: string): string

Generates filename to be used for outputs generation. The file itself is not created.

Parameters
- desiredFilename: string
Returns string

Pathname to be used for file generation.

getOutputUrl

getOutputUrl(tempPathname: string): string

Get URL for output pathname.

Parameters
- tempPathname: string
  
  Pathname to local output file.
Returns string

URL for the file.

getOutputUrlAsync

getOutputUrlAsync(tempPathname: string): Promise<string>

Get URL for output pathname.

Parameters
- tempPathname: string
  
  Pathname to local output file.
Returns Promise<string>

Promise with URL for the file.

getUrl

getUrl(resourceOrUrl: ResourceFile | string): string

Returns a URL for the resource definition or URL. See also loadFile. This is used when the resource needs to be accessed via a URL, such as STL and Textures. Use loadFile when the resource needs to be accessed as a file, such as an SQLite database or Excel file.

Parameters
- resourceOrUrl: ResourceFile | string
  
  The resource desired or URL
Returns string

isKindOf

isKindOf(model: Instance, designName: string): boolean

Returns true if model inherits from designName at any level

Parameters
- model: Instance
  
  The model to test
- designName: string
  
  The design name to look for
Returns boolean

isOutputFile

isOutputFile(filename: string): boolean

Returns true if pathname is for output file.

Parameters
- filename: string
Returns boolean

isOutputUrl

isOutputUrl(url: string): boolean

Returns true if url is for output file.

Parameters
- url: string
Returns boolean

isOutputUrlAsync

isOutputUrlAsync(url: string): Promise<boolean>

Returns Boolean promise, which is true if url is for output file.

Parameters
- url: string
Returns Promise<boolean>

makeBBox

makeBBox(...points: Point[]): BBox

Creates and returns a BBox object. If no points are provided, creates an empty BBox.

Parameters
- Rest ...points: Point[]
  
  Any number of Point objects
Returns BBox

makeLine

makeLine(p0: Point, p1: Point): Line

Creates a low-level Line geometry object for use with geometric computations.

Parameters
- p0: Point
  
  First point.
- p1: Point
  
  Second point.
Returns Line

makePlane

makePlane(p: Point, n: Vector): Plane

Creates and returns a Plane object.

Parameters
- p: Point
  
  Point which the plane passes through
- n: Vector
  
  Plane normal vector
Returns Plane

minimumSpanningTree

minimumSpanningTree(graph: any, startNode: string, weightAttributeName?: string): any

Computes the Minimum Spanning Tree of the graph, which is returned in the form of ??

Parameters
- graph: any
- startNode: string
- Optional weightAttributeName: string
Returns any

nextHigherInstance

nextHigherInstance(model: Instance, designName: string): Instance

Returns the next higher instance of designName from this

Parameters
- model: Instance
  
  The starting point
- designName: string
  
  The design name to look for
Returns Instance

nha

nha(model: Instance): Instance

Return the "next higher assembly" (ignoring the group level) for model

Parameters
- model: Instance
  
  Model for which the real parent is wanted
Returns Instance

offsetPoly

offsetPoly(pts: Point[], dist: number, ignore?: number): Point[][]

Offsets a polygon as defined by a single loop of Points. This is a back-compatible simplified version of the Polygon.offset2 method, which supports multi-valued offset distances and different corner treatments. For new work, use that method instead.

Parameters
- pts: Point[]
  
  Set of points to be offset. Treated as a closed loop.
- dist: number
  
  Distance to offset (negative values offset "inward")
- Optional ignore: number
Returns Point[][]

An array of point loops.

planeOfPoints

planeOfPoints(pts: Point[]): Plane

Creates a plane object defined by the first three non-collinear points in pts.

Parameters
- pts: Point[]
  
  A list of Points
Returns Plane

polygonToCurveTo

polygonToCurveTo(pts: Point[]): CurveTo[]

Converts an XY polygon (or polyline) to a CurveTo list. This simply ignores the Z coordinate of the points passed in; it does no transformation.

Parameters
- pts: Point[]
  
  The XY points representing the polygon.
Returns CurveTo[]

radians

radians(degrees: number): number

Convert degrees to radians.

Parameters
- degrees: number
Returns number

refMethod

refMethod(refchain: string, ...args: any[]): any

Evaluate method.

example

R.refMethod('root.sum', 1, 2)

Parameters
- refchain: string
- Rest ...args: any[]
Returns any

removeDuplicates

removeDuplicates(set: any[], keyf?: KeyFunction, matchf?: MatchFunction): any[]

Removes duplicates from an array, returning a new array.
example
```
// Simple test
removeDuplicates([1,7,2,2,3,4,5,1,7]) => [1,7,2,3,4,5]
```
Parameters
- set: any[]
  
  The set to operate on
- Optional keyf: KeyFunction
  
  Function which determines the "key" for an object. Objects with the same key are considered identical. The default is the item itself.
- Optional matchf: MatchFunction
  
  Function which determines whether two "keys" match. The default is ===.
Returns any[]

rgb

rgb(r: number, g: number, b: number): Color

This method creates a three.js Color object. These are used by some Designs, such as PointCloud, but cannot be used directly by the standard color parameter of Render3Mixin. However, it can be used to translate from one color space, such as HSL, to hex, for use in the color parameter. See the example below.
example
```
// Suppose we have an HSL color
//hue = 300; // 0 to 360, a "color wheel"
//saturation = 100%;
//lightness = 50%
const HSL = R.rgb("hsl(300,100%,50%)");
const hex = HSL.getHexString();
const colorString = `#${hex}`;
colorString => '#ff00fe'(~Magenta)
// Note that getHexString does not return the '#' or '0x" prefix.
```
Parameters
- r: number
  
  The red component of the color, number between 0 and 1, inclusive. OR a string containing any color spec acceptable to CSS, such as HSL, a color name, hex, etc.
- g: number
  
  The green component of the color, number between 0 and 1, inclusive.
- b: number
  
  The blue component of the color, number between 0 and 1, inclusive.
Returns Color

roundDown

roundDown(n: number, inc: number): number

Round n down to the nearest increment of inc. Rounds toward -Infinity. Increments always include zero.

Parameters
- n: number
  
  the number to round
- inc: number
  
  the increment size
Returns number

roundInc

roundInc(n: number, inc: number): number

Round n to the nearest increment of inc. Rounds up (toward +Infinity) when n is exactly in between two increments. Increments always include zero.

Parameters
- n: number
  
  the number to round
- inc: number
  
  the increment size
Returns number

roundUp

roundUp(n: number, inc: number): number

Round n up to the nearest increment of inc. Rounds toward +Infinity. Increments always include zero.

Parameters
- n: number
  
  the number to round
- inc: number
  
  the increment size
Returns number

safeRef

safeRef(refchainOrModel: string | Instance, ruleName?: string): any

"Safely" evaluates a refChain. This means that it will not throw an exception if any part of the refChain is invalid, but it will still return an exception if the valid refChain creates one.

Parameters
- refchainOrModel: string | Instance
  
  A refchain to a value, or a model
- Optional ruleName: string
  
  Optional rule to be evaluated (first arg must be a model)
Returns any

undefined if any part of the chain is invalid. This cannot be distinguished from a rule returning undefined.

setDifference

setDifference(a: any[], b: any[], keyf?: KeyFunction, matchf?: MatchFunction): any[]

Performs a set difference on two arrays, returning a new array.
example
```
// Simple test
setDifference([1,2,3,4,5], [2,5]) => [1,3,4]

// Key test
const setA = [{a: "a", b: 1},{a: "b", b: 2},{a: "c", b: 2}];
const setB = [{a: "b", b: 2}];
const keyf = (x:any) => x.b;
setDifference(setA,setB,keyf); => [{a: "a", b: 1}]
```
Parameters
- a: any[]
  
  First set of objects
- b: any[]
  
  Second set of objects
- Optional keyf: KeyFunction
  
  Function which determines the "key" for an object. Objects with the same key are considered identical. The default is the item itself.
- Optional matchf: MatchFunction
  
  Function which determines whether two "keys" match. The default is ===.
Returns any[]

setIntersection

setIntersection(a: any[], b: any[], keyf: KeyFunction, matchf: MatchFunction): any[]

Performs a set intersection on two arrays, returning a new array.
example
```
// Simple test
setIntersection([1,2,3,4,5], [2,5,6,7]) => [2,5]

// Key test
const setA = [{a: "a", b: 1},{a: "b", b: 2},{a: "c", b: 2}];
const setB = [{a: "x", b: 2}];
const keyf = (x:any) => x.b;
setIntersection(setA,setB,keyf); => [{a: "b", b: 2}]
```
Note: because the key function uses the "b" property, and two of the items in setA have the same b value, they are considered equivalent to each other and the item in setB. The function will pick one of them.
Parameters
- a: any[]
  
  First set of objects
- b: any[]
  
  Second set of objects
- keyf: KeyFunction
  
  Optional. Function which determines the "key" for an object. Objects with the same key are considered identical. The default is the item itself.
- matchf: MatchFunction
  
  Optional. Function which determines whether two "keys" match. The default is ===.
Returns any[]

setUnion

setUnion(a: any[], b: any[], keyf: KeyFunction, matchf: MatchFunction): any[]

Performs a set union on two arrays, returning a new array.

example

// Simple test
setUnion([1,2,3,4,5], [2,5,6,7]) => [1,2,3,4,5,6,7]

// Match test
const setA = [{x: 0, y: 1},{x: 0, y: 2},{x: 1, y: 2.001}];
const setB = [{x: 1.01, y: 2},{x: 1, y: 2.008}];
const keyf = (p:any) => p; // Identity
const matchf = (a:any, b:any) => (Math.abs(a.x-b.x)<0.05) && (Math.abs(a.y-b.y)<0.05)
setUnion(setA,setB,keyf,matchf); => [{x: 0, y: 1},{x: 0, y: 2},{x: 1, y: 2.001},{x: 1.01, y: 2}]

Parameters

a: any[]

First set of objects
b: any[]

Second set of objects
keyf: KeyFunction

Optional. Function which determines the "key" for an object. Objects with the same key are considered identical. The default is the item itself.
matchf: MatchFunction

Optional. Function which determines whether two "keys" match. The default is ===.

Returns any[]

sin

sin(deg: number): number

Returns the sine of the angle.

Parameters
- deg: number
  
  The angle in degrees
Returns number

tan

tan(deg: number): number

Returns the tangent of the angle.

Parameters
- deg: number
  
  The angle in degrees.
Returns number

transformPoints

transformPoints(points: any[], transform: Frame): any[]

Mass-transforms a set of points

Parameters
- points: any[]
  
  The point set to be converted. May be Point[], or Point[][]
- transform: Frame
  
  The transform to be applied
Returns any[]

A new set of points that have been transformed.

treeTraverse

treeTraverse(start: Instance, selector: function, userData?: any, rejector?: function, ignoreErrors?: boolean): Instance[]

Traverses the tree from start, and returns an array of all matching descendants. At each node in the tree, first the selector function is used to determine if this node should be collected, and then the rejector function is used to determine if the children of this node should be processed. UserData is supplied as the second argument to both functions, to allow passing in of addition information to the functions. If you are going to use userData, your function needs to be declared to take two arguments.

Note: This demands the tree, and will demand nodes that may not be completely working. It is up to the author to filter such nodes out (using the selector function), or write rules to ensure the tree is expandable.
example
```
// Collect all Blocks in the tree
R.treeTraverse(this, n => n.isKindOf('Block'))

// Collect all things like blocks that are not actual Blocks
R.treeTraverse(this, n => n.isKindOf("BoxMixin"), {}, n => !n.isKindOf('Block'))

// Collect every Block within a distance of a point (contrived use for userData)
R.treeTraverse(this, (n,d) => n.isKindOf('Block') && (n.origin.dist(d.point) < 5), { point: somePoint })
```
Parameters
- start: Instance
  
  The starting Model instance. Use "this" to start at the calling model.
- selector: function
  
  The selection function. Should return true when a match is found.
  - - (node: Instance, userData: any): boolean
    - Parameters
      - node: Instance
      - userData: any
      Returns boolean
- Optional userData: any
  
  Optional object which can be used to pass in more arguments. Default is {}.
- Optional rejector: function
  
  A function that determines whether to process the children. Should return true when the children of its argument should be processed. Default is (node, userData) => true.
  - - (node: Instance, userData: any): boolean
    - Parameters
      - node: Instance
      - userData: any
      Returns boolean
- Optional ignoreErrors: boolean
  
  Optional Boolean (defaulting to false) which will skip over errors while demanding the tree.
Returns Instance[]

uniqueName

uniqueName(seed: string, uniqueInModel?: Instance): string

Returns a unique identifier. If a model is provided, the string is unique (not used as an identifier) within that context.

Parameters
- seed: string
  
  The string which will have an integer appended.
- Optional uniqueInModel: Instance
  
  If supplied, the returned string is guaranteed to be unique in the given model.
Returns string

Hierarchy

Index

Properties

Accessors

Methods

Properties

Readonly demandChildren

geom

Readonly loadFile

message

model

nullHandle

Readonly ref

reflect

Readonly typeCheck

Readonly update

Accessors

rootModel

settings

symbols

version

world

Methods

AAA

Parameters

axis: Vector

Returns Vector

acos

Parameters

x: number

Returns number

asin

Parameters

x: number

Returns number

asleep

Parameters

model: Instance

Returns boolean

atan

Parameters

ratio: number

Returns number

atan2

Parameters

y: number

x: number

Returns number

computeTransform

Parameters

fromFrame: Frame

toFrame: Frame

Returns Frame

cos

Parameters

deg: number

Returns number

degrees

Parameters

radians: number

Returns number

error

Parameters

message: string

Returns never

gencat

Parameters

a: string | []

b: string | []

Returns any

getAllRules

Parameters

model: Instance

Returns RuleDescriptor[]

getModelJson

Parameters

model: Instance

Optional name: string

Returns string

getOutputDir