Module: AMS::Geometry

Defined in:

docs/ams/geometry.rb

Overview

Since:

• 3.3.0

Class Method Summary

• .angle_between_vectors(*args) ⇒ Numeric

  The angle in radians.

• .blend_colors(colors, ratio) ⇒ Sketchup::Color

  Transition between multiple colors.

• .calc_cubic_bezier_point(ratio, p0, p1, p2, p3) ⇒ Geom::Point3d

  Compute point on cubic bezier curve.

• .calc_cubic_bezier_slope(ratio, p0, p1, p2, p3) ⇒ Geom::Vector3d

  Compute slope on cubic bezier curve.

• .calc_edge_centre(edge) ⇒ Geom::Point3d

  Calculate edge centre of mass.

• .calc_face_centre(face) ⇒ Geom::Point3d

  Calculate face centre of mass.

• .deepray1(point, vector, chg = false) ⇒ Array<Array>

  Cast a continuous ray that intersects with all the entities.

• .deepray2(entities, point, vector, chg = false) ⇒ Array<Array>

  Cast a continuous ray that intersects with the given entities only.

• .deepray3(entities, point, vector, chg = false) ⇒ Array<Array>

  Cast a continuous ray that intersects with all but the given entities.

• .extract_matrix_scale(transformation) ⇒ Geom::Transformation

  Normalize the scale of axes of a transformation matrix.

• .extract_matrix_w_factor(transformation) ⇒ Geom::Transformation

  Scales the matrix so that its fifteenths component is 1.0.

• .get_matrix_scale(transformation) ⇒ Geom::Vector3d

  Get the scale of axes of a transformation matrix.

• .get_noncollinear_points(points) ⇒ Array<Geom::Point3d>^?

  Get three non-collinear points from an array of three or more points.

• .get_plane_normal(plane) ⇒ Geom::Vector3d

  Get plane normal.

• .get_points_on_circle2d(origin, radius, num_seg = 16, rot_angle = 0.0) ⇒ Array<Geom::Point3d>

  Get points of a two dimensional circle.

• .get_points_on_circle3d(origin, normal, radius, num_seg = 16, rot_angle = 0) ⇒ Array<Geom::Point3d>

  Get points of a three dimensional circle.

• .get_unique_points(points) ⇒ Array<Geom::Point3d>

  Get an array of unique points from an array of Point3d objects.

• .intersect_ray_triangle(origin, direction, pt1, pt2, pt3) ⇒ Geom::Point3d^?

  Intersect ray with a triangle.

• .is_matrix_flipped?(transformation) ⇒ Boolean

  Determine whether a transformation matrix is flipped.

• .is_matrix_uniform?(transformation) ⇒ Boolean

  Determine whether a transformation matrix is uniform.

• .is_point_on_edge?(point, edge) ⇒ Boolean

  Determine whether a particular point in on edge.

• .is_point_on_face?(point, face) ⇒ Boolean

  Determine whether a particular point is on face.

• .is_point_on_triangle?(point, pt1, pt2, pt3) ⇒ Boolean

  Determine whether a particular point is on triangle.

• .points_collinear?(points) ⇒ Boolean

  Determine whether an array of points lie on the same line.

• .points_coplanar?(points) ⇒ Boolean

  Determine whether an array of points lie on the same plane.

• .product_vector(vector1, vector2) ⇒ Geom::Vector3d

  Product two vectors - multiply their components.

• .raytest1(entities, point, vector, chg = false) ⇒ Array^?

  Cast a ray through the model that intersects with the given entities only.

• .raytest2(entities, point, vector, chg = false) ⇒ Array^?

  Cast a ray through the model that intersects with all but the given entities.

• .raytest3(point, vector, chg = false) ⇒ Array^?

  Cast a ray that intersects with non-transparent faces only; a ray that passes through all the transparent faces and stops when hits a solid face.

• .rotate_matrix_xaxis_to_dir(transformation, direction) ⇒ Geom::Transformation

  Rotate a transformation matrix so that its X-axis aligns with a directing vector.

• .rotate_matrix_yaxis_to_dir(transformation, direction) ⇒ Geom::Transformation

  Rotate a transformation matrix so that its Y-axis aligns with a directing vector.

• .rotate_matrix_zaxis_to_dir(transformation, direction) ⇒ Geom::Transformation

  Rotate a transformation matrix so that its Z-axis aligns with a directing vector.

• .rotate_vector(vector, normal, angle) ⇒ Geom::Vector3d

  Rotate vector at a normal.

• .scale_matrix(matrix, scale) ⇒ Geom::Transformation

  Scale matrix axes.

• .scale_point(point, scale) ⇒ Geom::Point3d

  Scale point.

• .scale_vector(vector, scale) ⇒ Geom::Vector3d

  Scale vector.

• .set_matrix_scale(transformation, scale) ⇒ Geom::Transformation

  Set the scale of axes of a transformation matrix.

• .sort_polygon_points(points) ⇒ Array<Geom::Point3d>

  Sort an array of points in a counter clockwise direction.

• .transition_camera(camera1, camera2, ratio) ⇒ Sketchup::Camera

  Transition between two cameras.

• .transition_color(color1, color2, ratio) ⇒ Sketchup::Color

  Transition between two colors.

• .transition_number(number1, number2, ratio) ⇒ Numeric

  between 0.0 and 1.0.

• .transition_point(point1, point2, ratio) ⇒ Geom::Point3d

  Transition between two points.

• .transition_transformation(transformation1, transformation2, ratio) ⇒ Geom::Transformation

  Transition between two transformation matrices.

• .transition_vector(vector1, vector2, ratio) ⇒ Geom::Vector3d

  Transition between two vectors.

Class Method Details

.angle_between_vectors(vector1, vector2) ⇒ Numeric .angle_between_vectors(vector1, vector2, normal) ⇒ Numeric

Returns The angle in radians.

Overloads:

• .angle_between_vectors(vector1, vector2) ⇒ Numeric

  Compute angle between two vectors.

  Parameters:

  • vector1 (Geom::Vector3d)
  • vector2 (Geom::Vector3d)
• .angle_between_vectors(vector1, vector2, normal) ⇒ Numeric

  Compute angle between two vectors at a normal.

  Parameters:

  • vector1 (Geom::Vector3d)
  • vector2 (Geom::Vector3d)
  • normal (Geom::Vector3d) —

    The normal to compute against.

Returns:

• (Numeric) —

  The angle in radians.

Since:

• 3.5.0

.blend_colors(colors, ratio) ⇒ Sketchup::Color

Transition between multiple colors.

Parameters:

• colors (Array<Sketchup::Color, String, Array>) —

  An array of colors to transition between.

• ratio (Numeric) —

  A value between 0.0 and 1.0.

Returns:

• (Sketchup::Color)

Since:

• 3.5.0

.calc_cubic_bezier_point(ratio, p0, p1, p2, p3) ⇒ Geom::Point3d

Compute point on cubic bezier curve.

Parameters:

• ratio (Numeric) —

  A value between 0.0 and 1.0.

• p0 (Geom::Point3d) —

  First point origin.

• p1 (Geom::Point3d) —

  First point target.

• p2 (Geom::Point3d) —

  Second point target.

• p3 (Geom::Point3d) —

  Second point origin.

Returns:

• (Geom::Point3d)

Since:

• 3.5.0

.calc_cubic_bezier_slope(ratio, p0, p1, p2, p3) ⇒ Geom::Vector3d

Compute slope on cubic bezier curve.

Parameters:

• ratio (Numeric) —

  A value between 0.0 and 1.0.

• p0 (Geom::Point3d) —

  First point origin.

• p1 (Geom::Point3d) —

  First point target.

• p2 (Geom::Point3d) —

  Second point target.

• p3 (Geom::Point3d) —

  Second point origin.

Returns:

• (Geom::Vector3d)

Since:

• 3.5.0

.calc_edge_centre(edge) ⇒ Geom::Point3d

Calculate edge centre of mass.

Parameters:

• edge (Sketchup::Edge)

Returns:

• (Geom::Point3d)

Since:

• 3.3.0

.calc_face_centre(face) ⇒ Geom::Point3d

Calculate face centre of mass.

Parameters:

• face (Sketchup::Face)

Returns:

• (Geom::Point3d)

Since:

• 3.3.0

.deepray1(point, vector, chg = false) ⇒ Array<Array>

Cast a continuous ray that intersects with all the entities.

Parameters:

• point (Geom::Point3d, Array) —

  Ray position.

• vector (Geom::Vector3d, Array) —

  Ray direction.

• chg (Boolean) (defaults to: false) —

  Whether to consider hidden geometry.

Returns:

• (Array<Array>) —

  An array of ray results.

See Also:

• http://ruby.sketchup.com/Sketchup/Model.html#raytest-instance_method

Since:

• 3.5.0

.deepray2(entities, point, vector, chg = false) ⇒ Array<Array>

Cast a continuous ray that intersects with the given entities only.

Parameters:

• entities (Array<Sketchup::Drawingelement>) —

  An array of entities to include.

• point (Geom::Point3d, Array) —

  Ray position.

• vector (Geom::Vector3d, Array) —

  Ray direction.

• chg (Boolean) (defaults to: false) —

  Whether to consider hidden geometry.

Returns:

• (Array<Array>) —

  An array of ray results.

See Also:

• http://ruby.sketchup.com/Sketchup/Model.html#raytest-instance_method

Since:

• 3.5.0

.deepray3(entities, point, vector, chg = false) ⇒ Array<Array>

Cast a continuous ray that intersects with all but the given entities.

Parameters:

• entities (Array<Sketchup::Drawingelement>) —

  An array of entities to ignore.

• point (Geom::Point3d, Array) —

  Ray position.

• vector (Geom::Vector3d, Array) —

  Ray direction.

• chg (Boolean) (defaults to: false) —

  Whether to consider hidden geometry.

Returns:

• (Array<Array>) —

  An array of ray results.

See Also:

• http://ruby.sketchup.com/Sketchup/Model.html#raytest-instance_method

Since:

• 3.5.0

.extract_matrix_scale(transformation) ⇒ Geom::Transformation

Normalize the scale of axes of a transformation matrix.

Parameters:

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

Returns:

• (Geom::Transformation) —

  A new, normalize transformation matrix.

Since:

• 3.3.0

.extract_matrix_w_factor(transformation) ⇒ Geom::Transformation

Scales the matrix so that its fifteenths component is 1.0.

Parameters:

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

Returns:

• (Geom::Transformation)

Since:

• 3.6.0

.get_matrix_scale(transformation) ⇒ Geom::Vector3d

Get the scale of axes of a transformation matrix.

Parameters:

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

Returns:

• (Geom::Vector3d) —

  A vector representing the scale ratios of the X-axis, Y-axis, and Z-axis.

Since:

• 3.3.0

.get_noncollinear_points(points) ⇒ Array<Geom::Point3d>^?

Get three non-collinear points from an array of three or more points.

Parameters:

• points (Array<Geom::Point3d>)

Returns:

• (Array<Geom::Point3d>, nil) —

  An array of three non-collinear points if successful.

Since:

• 3.3.0

.get_plane_normal(plane) ⇒ Geom::Vector3d

Get plane normal.

Parameters:

• plane (Array<Geom::Point3d>) —

  An array of three, non-collinear points on the plane.

Returns:

• (Geom::Vector3d)

Since:

• 3.3.0

.get_points_on_circle2d(origin, radius, num_seg = 16, rot_angle = 0.0) ⇒ Array<Geom::Point3d>

Get points of a two dimensional circle.

Parameters:

• origin (Array<Numeric>)
• radius (Numeric)
• num_seg (Integer) (defaults to: 16) —

  Number of segments.

• rot_angle (Numeric) (defaults to: 0.0) —

  Rotate angle in radians.

Returns:

• (Array<Geom::Point3d>) —

  An array of points making up the circle.

Since:

• 3.5.0

.get_points_on_circle3d(origin, normal, radius, num_seg = 16, rot_angle = 0) ⇒ Array<Geom::Point3d>

Get points of a three dimensional circle.

Parameters:

• origin (Array<Numeric>, Geom::Point3d)
• normal (Array<Numeric>, Geom::Vector3d)
• radius (Numeric)
• num_seg (Integer) (defaults to: 16) —

  Number of segments.

• rot_angle (Numeric) (defaults to: 0) —

  Rotate angle in radians.

Returns:

• (Array<Geom::Point3d>) —

  An array of points making up the circle.

Since:

• 3.5.0

.get_unique_points(points) ⇒ Array<Geom::Point3d>

Get an array of unique points from an array of Point3d objects.

Parameters:

• points (Array<Geom::Point3d>)

Returns:

• (Array<Geom::Point3d>)

Since:

• 3.3.0

.intersect_ray_triangle(origin, direction, pt1, pt2, pt3) ⇒ Geom::Point3d^?

Intersect ray with a triangle.

Parameters:

• origin (Geom::Point3d) —

  The origin of the ray.

• direction (Geom::Vector3d) —

  The direction of the ray.

• pt1 (Geom::Point3d) —

  The first vertex of the triangle.

• pt2 (Geom::Point3d) —

  The second vertex of the triangle.

• pt3 (Geom::Point3d) —

  The third vertex of the triangle.

Returns:

• (Geom::Point3d, nil)

See Also:

• http://www.cs.virginia.edu/~gfx/Courses/2003/ImageSynthesis/papers/Acceleration/Fast%20MinimumStorage%20RayTriangle%20Intersection.pdf

Since:

• 3.3.0

.is_matrix_flipped?(transformation) ⇒ Boolean

Determine whether a transformation matrix is flipped.

Parameters:

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

Returns:

• (Boolean)

Since:

• 3.3.0

.is_matrix_uniform?(transformation) ⇒ Boolean

Determine whether a transformation matrix is uniform. A uniform transformation matrix has its axes perpendicular to each other.

Parameters:

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

Returns:

• (Boolean)

Since:

• 3.3.0

.is_point_on_edge?(point, edge) ⇒ Boolean

Determine whether a particular point in on edge.

Parameters:

• point (Geom::Point3d)
• edge (Sketchup::Edge)

Returns:

• (Boolean)

Since:

• 3.3.0

.is_point_on_face?(point, face) ⇒ Boolean

Determine whether a particular point is on face.

Parameters:

• point (Geom::Point3d)
• face (Sketchup::Face)

Returns:

• (Boolean)

Since:

• 3.3.0

.is_point_on_triangle?(point, pt1, pt2, pt3) ⇒ Boolean

Determine whether a particular point is on triangle.

Parameters:

• point (Geom::Point3d) —

  The point to test.

• pt1 (Geom::Point3d) —

  The first vertex of the triangle.

• pt2 (Geom::Point3d) —

  The second vertex of the triangle.

• pt3 (Geom::Point3d) —

  The third vertex of the triangle.

Returns:

• (Boolean)

Since:

• 3.3.0

.points_collinear?(points) ⇒ Boolean

Determine whether an array of points lie on the same line.

Parameters:

• points (Array<Geom::Point3d>)

Returns:

• (Boolean)

Since:

• 3.3.0

.points_coplanar?(points) ⇒ Boolean

Determine whether an array of points lie on the same plane.

Parameters:

• points (Array<Geom::Point3d>)

Returns:

• (Boolean)

Since:

• 3.3.0

.product_vector(vector1, vector2) ⇒ Geom::Vector3d

Product two vectors - multiply their components.

Parameters:

• vector1 (Array<Numeric>, Geom::Vector3d)
• vector2 (Array<Numeric>, Geom::Vector3d)

Returns:

• (Geom::Vector3d)

Since:

• 3.6.0

.raytest1(entities, point, vector, chg = false) ⇒ Array^?

Cast a ray through the model that intersects with the given entities only.

Parameters:

• entities (Array<Sketchup::Drawingelement>) —

  An array of entities to include.

• point (Geom::Point3d, Array) —

  Ray position.

• vector (Geom::Vector3d, Array) —

  Ray direction.

• chg (Boolean) (defaults to: false) —

  Whether to consider hidden geometry.

Returns:

• (Array, nil) —

  A ray result.

See Also:

• http://ruby.sketchup.com/Sketchup/Model.html#raytest-instance_method

Since:

• 3.5.0

.raytest2(entities, point, vector, chg = false) ⇒ Array^?

Cast a ray through the model that intersects with all but the given entities.

Parameters:

• entities (Array<Sketchup::Drawingelement>) —

  An array of entities to ignore.

• point (Geom::Point3d, Array) —

  Ray position.

• vector (Geom::Vector3d, Array) —

  Ray direction.

• chg (Boolean) (defaults to: false) —

  Whether to consider hidden geometry.

Returns:

• (Array, nil) —

  A ray result.

See Also:

• http://ruby.sketchup.com/Sketchup/Model.html#raytest-instance_method

Since:

• 3.5.0

.raytest3(point, vector, chg = false) ⇒ Array^?

Note:

A face is considered transparent if front or back side, depending on which the ray hits, has a material with alpha less than 255.

Cast a ray that intersects with non-transparent faces only; a ray that passes through all the transparent faces and stops when hits a solid face.

Parameters:

• point (Geom::Point3d, Array) —

  Ray position.

• vector (Geom::Vector3d, Array) —

  Ray direction.

• chg (Boolean) (defaults to: false) —

  Whether to consider hidden geometry.

Returns:

• (Array, nil) —

  A ray result.

See Also:

• http://ruby.sketchup.com/Sketchup/Model.html#raytest-instance_method

Since:

• 3.5.0

.rotate_matrix_xaxis_to_dir(transformation, direction) ⇒ Geom::Transformation

Rotate a transformation matrix so that its X-axis aligns with a directing vector.

Parameters:

• transformation (Geom::Transformation)
• direction (Geom::Vector)

Returns:

• (Geom::Transformation)

Since:

• 3.5.0

.rotate_matrix_yaxis_to_dir(transformation, direction) ⇒ Geom::Transformation

Rotate a transformation matrix so that its Y-axis aligns with a directing vector.

Parameters:

• transformation (Geom::Transformation)
• direction (Geom::Vector)

Returns:

• (Geom::Transformation)

Since:

• 3.5.0

.rotate_matrix_zaxis_to_dir(transformation, direction) ⇒ Geom::Transformation

Rotate a transformation matrix so that its Z-axis aligns with a directing vector.

Parameters:

• transformation (Geom::Transformation)
• direction (Geom::Vector)

Returns:

• (Geom::Transformation)

Since:

• 3.5.0

.rotate_vector(vector, normal, angle) ⇒ Geom::Vector3d

Rotate vector at a normal.

Parameters:

• vector (Geom::Vector3d) —

  The vector to rotate.

• normal (Geom::Vector3d) —

  The normal to rotate against.

• angle (Numeric) —

  The angle to rotate in radians.

Returns:

• (Geom::Vector3d) —

  The rotated vector.

Since:

• 3.5.0

.scale_matrix(matrix, scale) ⇒ Geom::Transformation

Scale matrix axes.

Parameters:

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

Returns:

• (Geom::Transformation)

Since:

• 3.6.0

.scale_point(point, scale) ⇒ Geom::Point3d

Scale point.

Parameters:

• point (Array<Numeric>, Geom::Point3d)
• scale (Numeric)

Returns:

• (Geom::Point3d)

Since:

• 3.5.0

.scale_vector(vector, scale) ⇒ Geom::Vector3d

Scale vector.

Parameters:

• vector (Array<Numeric>, Geom::Vector3d)
• scale (Numeric)

Returns:

• (Geom::Vector3d)

Since:

• 3.5.0

.set_matrix_scale(transformation, scale) ⇒ Geom::Transformation

Set the scale of axes of a transformation matrix.

Parameters:

• transformation (Geom::Transformation, Array<Numeric>)
• scale (Geom::Vector3d, Array<Numeric>) —

  An array of three numeric values, representing the scale ratios of the X-axis, Y-axis, and Z-axis.

Returns:

• (Geom::Transformation) —

  A new, scaled transformation matrix.

Since:

• 3.3.0

.sort_polygon_points(points) ⇒ Array<Geom::Point3d>

Note:

A polygon must be convex for the points to be sorted correctly.

Note:

If all points are collinear, then they won't be sorted and an array of unique points will be returned.

Sort an array of points in a counter clockwise direction.

Parameters:

• points (Array<Geom::Point3d>)

Returns:

• (Array<Geom::Point3d>) —

  An array of sorted points.

Since:

• 3.3.0

.transition_camera(camera1, camera2, ratio) ⇒ Sketchup::Camera

Transition between two cameras.

Parameters:

• camera1 (Sketchup::Camera)
• camera2 (Sketchup::Camera)
• ratio (Numeric) —

  A value between 0.0 and 1.0.

Returns:

• (Sketchup::Camera)

Since:

• 3.3.0

.transition_color(color1, color2, ratio) ⇒ Sketchup::Color

Transition between two colors.

Parameters:

• color1 (Sketchup::Color)
• color2 (Sketchup::Color)
• ratio (Numeric) —

  A value between 0.0 and 1.0.

Returns:

• (Sketchup::Color)

Since:

• 3.3.0

.transition_number(number1, number2, ratio) ⇒ Numeric

between 0.0 and 1.0.

Returns:

• (Numeric)

Since:

• 3.3.0

.transition_point(point1, point2, ratio) ⇒ Geom::Point3d

Transition between two points.

Parameters:

• point1 (Geom::Point3d)
• point2 (Geom::Point3d)
• ratio (Numeric) —

  A value, not necessarily between 0.0 and 1.0.

Returns:

• (Geom::Point3d)

Since:

• 3.3.0

.transition_transformation(transformation1, transformation2, ratio) ⇒ Geom::Transformation

Note:

For the function to work properly, both transformation matrices must be uniform and non-flipped. They can, however, since version 3.5.0, have scaled axes.

Transition between two transformation matrices.

Parameters:

• transformation1 (Geom::Transformation)
• transformation2 (Geom::Transformation)
• ratio (Numeric) —

  A value, not necessarily between 0.0 and 1.0.

Returns:

• (Geom::Transformation)

Since:

• 3.3.0

.transition_vector(vector1, vector2, ratio) ⇒ Geom::Vector3d

Note:

Unlike the transition_point function, this function rotates and scales vector1 to vector2 a specific ratio.

Transition between two vectors.

Parameters:

• vector1 (Geom::Vector3d)
• vector2 (Geom::Vector3d)
• ratio (Numeric) —

  A value, not necessarily between 0.0 and 1.0.

Returns:

• (Geom::Vector3d)

Since:

• 3.3.0