Class: MSPhysics::Joint

Inherits:
Entity
  • Object
show all
Defined in:
RubyExtension/MSPhysics/joint.rb

Overview

An abstract for all joints.

Since:

  • 1.0.0

Constant Summary collapse

DEFAULT_SOLVER_MODEL =

Since:

  • 1.0.0

2
DEFAULT_STIFFNESS =

Since:

  • 1.0.0

1.00
DEFAULT_BODIES_COLLIDABLE =

Since:

  • 1.0.0

false
DEFAULT_BREAKING_FORCE =

Since:

  • 1.0.0

0.0

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Entity

#inspect, #to_s

Constructor Details

#initialize(world, parent, pin_tra, group_inst = nil) ⇒ Joint

Returns a new instance of Joint.

Parameters:

  • world (MSPhysics::World)
  • parent (MSPhysics::Body, nil)
  • pin_tra (Geom::Transformation, Array<Numeric>) —

    Pin transformation in global space. Matrix origin is interpreted as the pin position. Matrix Z-axis is interpreted as the pin direction.

  • group_inst (Sketchup::Group, Sketchup::ComponentInstance, nil) (defaults to: nil)

Since:

  • 1.0.0



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'RubyExtension/MSPhysics/joint.rb', line 58

def initialize(world, parent, pin_tra, group_inst = nil)
  if self.class == MSPhysics::Joint
    raise(TypeError, "Creating an instance of the Joint abstract class is not allowed!", caller)
  end
  MSPhysics::World.validate(world)
  MSPhysics::Body.validate(parent, world) if parent
  parent_address = parent ? parent.address : nil
  @address = MSPhysics::Newton::Joint.create(world.address, parent_address, pin_tra, group_inst)
  MSPhysics::Newton::Joint.set_user_data(@address, self)
  MSPhysics::Newton::Joint.set_stiffness(@address, DEFAULT_STIFFNESS)
  MSPhysics::Newton::Joint.set_bodies_collidable(@address, DEFAULT_BODIES_COLLIDABLE)
  MSPhysics::Newton::Joint.set_breaking_force(@address, DEFAULT_BREAKING_FORCE)
  MSPhysics::Newton::Joint.set_solver_model(@address, DEFAULT_SOLVER_MODEL)
  @name = ''
end

Class Method Details

.all_joints ⇒ Array<Joint>

Note:

Joints that do not have a MSPhysics::Joint instance are not included in the array.

Get all joints.

Returns:

Since:

  • 1.0.0



46
47
48
 
# File 'RubyExtension/MSPhysics/joint.rb', line 46

def all_joints
  MSPhysics::Newton.get_all_joints() { |ptr, data| data.is_a?(MSPhysics::Joint) ? data : nil }
end

.joint_by_address(address) ⇒ Joint?

Get joint by address.

Parameters:

  • address (Integer)

Returns:

  • (Joint, nil) —

    A Joint object if successful.

Raises:

  • (TypeError) —

    if the address is invalid.

Since:

  • 1.0.0



37
38
39
40
 
# File 'RubyExtension/MSPhysics/joint.rb', line 37

def joint_by_address(address)
  data = MSPhysics::Newton::Joint.get_user_data(address.to_i)
  data.is_a?(MSPhysics::Joint) ? data : nil
end

.validate(joint, world = nil) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Verify that joint is valid.

Parameters:

  • joint (Joint)
  • world (World, nil) (defaults to: nil) —

    A world the joint ought to belong to or nil.

Raises:

  • (TypeError) —

    if joint is invalid or destroyed.

Since:

  • 1.0.0



20
21
22
23
24
25
26
27
28
29
30
31
 
# File 'RubyExtension/MSPhysics/joint.rb', line 20

def validate(joint, world = nil)
  AMS.validate_type(joint, MSPhysics::Joint)
  unless joint.valid?
    raise(TypeError, "Joint #{joint} is invalid/destroyed!", caller)
  end
  if world != nil
    AMS.validate_type(world, MSPhysics::World)
    if joint.world.address != world.address
      raise(TypeError, "Joint #{joint} belongs to a different world!", caller)
    end
  end
end

Instance Method Details

#address ⇒ Integer

Get pointer the joint.

Returns:

  • (Integer)

Since:

  • 1.0.0



82
83
84
 
# File 'RubyExtension/MSPhysics/joint.rb', line 82

def address
  @address
end

#bodies_collidable=(state) ⇒ Object

Set parent body collidable/noncollidable with its child body.

Parameters:

  • state (Boolean)

Since:

  • 1.0.0



186
187
188
 
# File 'RubyExtension/MSPhysics/joint.rb', line 186

def bodies_collidable=(state)
  MSPhysics::Newton::Joint.set_bodies_collidable(@address, state)
end

#bodies_collidable? ⇒ Boolean

Determine whether parent body is collidable with its child body.

Returns:

  • (Boolean)

Since:

  • 1.0.0



180
181
182
 
# File 'RubyExtension/MSPhysics/joint.rb', line 180

def bodies_collidable?
  MSPhysics::Newton::Joint.bodies_collidable?(@address)
end

#breaking_force ⇒ Numeric

Get joint breaking force in Newtons.

Returns:

  • (Numeric)

Since:

  • 1.0.0



204
205
206
 
# File 'RubyExtension/MSPhysics/joint.rb', line 204

def breaking_force
  MSPhysics::Newton::Joint.get_breaking_force(@address)
end

#breaking_force=(force) ⇒ Object

Set joint breaking force in Newtons.

Parameters:

  • force (Numeric)

Since:

  • 1.0.0



210
211
212
 
# File 'RubyExtension/MSPhysics/joint.rb', line 210

def breaking_force=(force)
  MSPhysics::Newton::Joint.set_breaking_force(@address, force)
end

#child ⇒ MSPhysics::Body?

Get joint child body.

Returns:

Since:

  • 1.0.0



147
148
149
150
 
# File 'RubyExtension/MSPhysics/joint.rb', line 147

def child
  address = MSPhysics::Newton::Joint.get_child(@address)
  address ? MSPhysics::Body.body_by_address(address) : nil
end

#connect(child) ⇒ Boolean

Connect joint to its desired child body.

Parameters:

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0



108
109
110
111
 
# File 'RubyExtension/MSPhysics/joint.rb', line 108

def connect(child)
  MSPhysics::Body.validate(child, self.world)
  MSPhysics::Newton::Joint.connect(@address, child.address)
end

#connected? ⇒ Boolean

Determine whether joint is connected to its child body.

Returns:

  • (Boolean)

Since:

  • 1.0.0



121
122
123
 
# File 'RubyExtension/MSPhysics/joint.rb', line 121

def connected?
  MSPhysics::Newton::Joint.is_connected?(@address)
end

#destroy ⇒ void

This method returns an undefined value.

Destroy joint.

Since:

  • 1.0.0



101
102
103
 
# File 'RubyExtension/MSPhysics/joint.rb', line 101

def destroy
  MSPhysics::Newton::Joint.destroy(@address)
end

#disconnect ⇒ Boolean

Disconnect joint from its child body.

Returns:

  • (Boolean) —

    success

Since:

  • 1.0.0



115
116
117
 
# File 'RubyExtension/MSPhysics/joint.rb', line 115

def disconnect
  MSPhysics::Newton::Joint.disconnect(@address)
end

#dof ⇒ Integer

Get joint maximum degrees of freedom.

Returns:

  • (Integer)

Since:

  • 1.0.0



127
128
129
 
# File 'RubyExtension/MSPhysics/joint.rb', line 127

def dof
  MSPhysics::Newton::Joint.get_dof(@address)
end

#get_pin_matrix ⇒ Geom::Transformation

Get joint pin transformation in global space.

Returns:

  • (Geom::Transformation)

Since:

  • 1.0.0



154
155
156
 
# File 'RubyExtension/MSPhysics/joint.rb', line 154

def get_pin_matrix
  MSPhysics::Newton::Joint.get_pin_matrix(@address)
end

#get_pin_matrix2(mode) ⇒ Geom::Transformation?

Get joint pin transformation in global space.

Parameters:

  • mode (Integer) —

    • Pass 0 to obtain aligned pin matrix in global space with respect to the child body.

    • Pass 1 to obtain aligned pin matrix in global space with respect to the parent body.

    • Pass 2 to obtain non-aligned pin matrix in global space with respect to the parent body.

Returns:

  • (Geom::Transformation, nil)

Since:

  • 1.0.0



174
175
176
 
# File 'RubyExtension/MSPhysics/joint.rb', line 174

def get_pin_matrix2(mode)
  MSPhysics::Newton::Joint.get_pin_matrix2(@address, mode)
end

#get_tension1 ⇒ Geom::Vecotor3d

Get primary tension force on a joint, which is usually the linear tension, in Newtons, in global space.

Returns:

  • (Geom::Vecotor3d)

Since:

  • 1.0.3



236
237
238
 
# File 'RubyExtension/MSPhysics/joint.rb', line 236

def get_tension1
  MSPhysics::Newton::Joint.get_tension1(@address)
end

#get_tension2 ⇒ Geom::Vecotor3d

Get secondary tension force on a joint, which is usually the angular tension, in Newton-meters, in global space.

Returns:

  • (Geom::Vecotor3d)

Since:

  • 1.0.3



244
245
246
 
# File 'RubyExtension/MSPhysics/joint.rb', line 244

def get_tension2
  MSPhysics::Newton::Joint.get_tension2(@address)
end

#group ⇒ Sketchup::Group, ...

Get group/component associated with the joint.

Returns:

  • (Sketchup::Group, Sketchup::ComponentInstance, nil)

Since:

  • 1.0.0



88
89
90
 
# File 'RubyExtension/MSPhysics/joint.rb', line 88

def group
  MSPhysics::Newton::Joint.get_group(@address)
end

#name ⇒ String

Get joint name.

Returns:

  • (String)

Since:

  • 1.0.0



250
251
252
 
# File 'RubyExtension/MSPhysics/joint.rb', line 250

def name
  @name.dup
end

#name=(value) ⇒ Object

Set joint name

Parameters:

  • value (String)

Since:

  • 1.0.0



256
257
258
 
# File 'RubyExtension/MSPhysics/joint.rb', line 256

def name=(value)
  @name = value.to_s.dup
end

#parent ⇒ MSPhysics::Body?

Get joint parent body.

Returns:

Since:

  • 1.0.0



140
141
142
143
 
# File 'RubyExtension/MSPhysics/joint.rb', line 140

def parent
  address = MSPhysics::Newton::Joint.get_parent(@address)
  address ? MSPhysics::Body.body_by_address(address) : nil
end

#set_pin_matrix(matrix) ⇒ nil

Set joint pin transformation in global space.

Parameters:

  • matrix (Geom::Transformation, Array<Numeric>)

Returns:

  • (nil)

Since:

  • 1.0.0



161
162
163
 
# File 'RubyExtension/MSPhysics/joint.rb', line 161

def set_pin_matrix(matrix)
  MSPhysics::Newton::Joint.set_pin_matrix(@address, matrix)
end

#solver_model ⇒ Integer

Get solver model for calculating the constraint forces.

Returns:

  • (Integer) —

    Model:

    • 0 - Use best algorithm.

    • 1 - Signal the engine that two joints form a kinematic loop.

    • 2 - Use less accurate algorithm.

Since:

  • 1.0.0



219
220
221
 
# File 'RubyExtension/MSPhysics/joint.rb', line 219

def solver_model
  MSPhysics::Newton::Joint.get_solver_model(@address)
end

#solver_model=(model) ⇒ Object

Set solver model for calculating the constraint forces.

Parameters:

  • model (Integer) —

    Solver model:

    • 0 - Use best algorithm.

    • 1 - Signal the engine that two joints form a kinematic loop.

    • 2 - Use less accurate algorithm.

Since:

  • 1.0.0



228
229
230
 
# File 'RubyExtension/MSPhysics/joint.rb', line 228

def solver_model=(model)
  MSPhysics::Newton::Joint.set_solver_model(@address, model)
end

#stiffness ⇒ Numeric

Get joint stiffness.

Returns:

  • (Numeric) —

    A value between 0.0 (soft) and 1.0 (stiff).

Since:

  • 1.0.0



192
193
194
 
# File 'RubyExtension/MSPhysics/joint.rb', line 192

def stiffness
  MSPhysics::Newton::Joint.get_stiffness(@address)
end

#stiffness=(value) ⇒ Object

Set joint stiffness

Parameters:

  • value (Numeric) —

    A value between 0.0 (soft) and 1.0 (stiff).

Since:

  • 1.0.0



198
199
200
 
# File 'RubyExtension/MSPhysics/joint.rb', line 198

def stiffness=(value)
  MSPhysics::Newton::Joint.set_stiffness(@address, value)
end

#type ⇒ Integer

Get joint type.

Returns:

  • (Integer)

See Also:

Since:

  • 1.0.0



134
135
136
 
# File 'RubyExtension/MSPhysics/joint.rb', line 134

def type
  MSPhysics::Newton::Joint.get_type(@address)
end

#valid? ⇒ Boolean

Determine whether joint is valid.

Returns:

  • (Boolean)

Since:

  • 1.0.0



76
77
78
 
# File 'RubyExtension/MSPhysics/joint.rb', line 76

def valid?
  MSPhysics::Newton::Joint.is_valid?(@address)
end

#world ⇒ MSPhysics::World

Get the world the joint is associated to.

Returns:

Since:

  • 1.0.0



94
95
96
97
 
# File 'RubyExtension/MSPhysics/joint.rb', line 94

def world
  world_address = MSPhysics::Newton::Joint.get_world(@address)
  MSPhysics::Newton::World.get_user_data(world_address)
end