Class: Sketchup::PickHelper

Inherits:
Object
  • Object
show all

Overview

Note:

The same Pickhelper instance is being reused by SketchUp. Don't extend, add methods or redefine methods on this object as it can clash with other extensions.

The PickHelper class is used to pick entities that reside under the current cursor location, similar to native Select tool. Unlike InputPoint, PickHelper uses no inference.

Only Tools react to cursor location and most of these methods are only useful in the context of a tool. For example, if you want to determine the entity you just clicked, you would use #do_pick from within your Tool#onLButtonDown method.

You can retrieve a PickHelper object using the View#pick_helper method.

Entities that are picked (found under the cursor when a mouse or keyboard event occurs), are called Pick Records and are placed in an indexed list.

Version:

  • SketchUp 6.0

Constants for PickHelper boundingbox_pick types # collapse

Sketchup::PickHelper::PICK_INSIDE
Sketchup::PickHelper::PICK_CROSSING

Instance Method Summary # collapse

Instance Method Details

↑ #all_picked ⇒ Object

The all_picked method is used to get an array of entities from the active entities from all the pick paths. Duplicates might occur if there are multiple pick paths for entities that ends in a group or component.

For example, if the pick hits at the border of an edge and face inside a group there will be two pick paths - one for the face and one for the edge. Since this method returns entities from the active entities it would return an array with the group two times.

Examples:

ph = view.pick_helper
ph.do_pick(x, y)
entities = ph.all_picked

Returns:

  • elements - the array of elements in the pick.

Version:

  • SketchUp 6.0

↑ #best_picked ⇒ Object

The best_picked method is used to retrieve the “best” entity picked (entity that you would have picked if you were using the select tool).

Returns nil if nothing was picked. You must have called do_pick before calling this method.

Examples:

ph = view.pick_helper
ph.do_pick(x, y)
best_entity = ph.best_picked

Returns:

  • entity - the best picked entity

Version:

  • SketchUp 6.0

↑ #boundingbox_pick(bounding_box, pick_type, transformation = IDENTITY) ⇒ Integer

Used to pick a set of entities from a model from a Geom::BoundingBox. The pick criteria can be for completely-contained or partially-contained entities, similar to how the Selection tool works.

Examples:

boundingbox = Geom::BoundingBox.new
boundingbox.add([1, 1, 1], [100, 100, 100])
ph = Sketchup.active_model.active_view.pick_helper

# Rotate the box 45' around the z-axis
angle = 45
transformation = Geom::Transformation.new(ORIGIN, Z_AXIS, angle)

num_picked = ph.boundingbox_pick(boundingbox, Sketchup::PickHelper::PICK_CROSSING,
  transformation)
if num_picked > 0
  Sketchup.active_model.selection.add(ph.all_picked)
end

Returns The number of entities picked.

Parameters:

  • bounding_box (Geom::BoundingBox) —

    Bounding box defining the volume to use for picking.

  • pick_type (Integer) —

    PICK_INSIDE to select entities completely contained or PICK_CROSSING to select entities partially contained.

  • transformation (Geom::Transformation) (defaults to: IDENTITY) —

    Transformation that will be applied to the volume defined by the bounding_box that allows for a rotation.

Returns:

  • (Integer) —

    The number of entities picked

Version:

  • SketchUp 2016

↑ #count ⇒ Object

The count method is used to count the number of entities picked (number of pick records)

Examples:

number = pickhelper.count

Returns:

  • number - the number of entities picked

Version:

  • SketchUp 6.0

↑ #depth_at(index) ⇒ Object

The depth_at method retrieves the depth of one of the currently picked entities in the list of pick records.

Examples:

pickhelper = view.pick_helper
pickhelper.do_pick(x, y)
# Iterate all pick-routes:
pickhelper.count.times { |pick_path_index|
  puts pickhelper.depth_at(pick_path_index)
}

Returns integer - the depth of the entity if successful.

Parameters:

  • index —

    A number from 0 to number of items picked minus one.

Returns:

  • integer - the depth of the entity if successful

Version:

  • SketchUp 6.0

↑ #do_pick(x, y, aperture = 0) ⇒ Integer #do_pick(x, y, aperture = 0.0) ⇒ Integer

The #do_pick method is used to perform the initial pick. This method is generally called before any other methods in the PickHelper class.

Examples:

ph = view.pick_helper
num = ph.do_pick(x, y)
entity = ph.best_picked

Overloads:

  • #do_pick(x, y, aperture = 0) ⇒ Integer
    Note:

    Signature for versions prior to SketchUp 2025.0

    Returns Number of entities picked.

    Parameters:

    • x (Integer) —

      Screen coordinate in physical pixels.

    • y (Integer) —

      Screen coordinate in physical pixels.

    • aperture (Integer) (defaults to: 0) —

      The size of the aperture in physical pixels.

    Returns:

    • (Integer) —

      Number of entities picked.

    Version:

    • SketchUp 6.0

  • #do_pick(x, y, aperture = 0.0) ⇒ Integer

    Returns Number of entities picked.

    Parameters:

    • x (Float) —

      Screen coordinate in logical pixels.

    • y (Float) —

      Screen coordinate in logical pixels.

    • aperture (Float) (defaults to: 0.0) —

      The size of the aperture in logical pixels.

    Returns:

    • (Integer) —

      Number of entities picked.

    Version:

    • SketchUp 2025.0

Version:

  • SketchUp 6.0

↑ #element_at(index) ⇒ Object

The element_at method is used to retrieve a specific entity in the list of picked elements. This element will be from the active entities.

Use count() to get the number of possible pick paths.

Examples:

pickhelper = view.pick_helper
pickhelper.do_pick(x, y)
# Iterate all pick-routes:
pickhelper.count.times { |pick_path_index|
  puts pickhelper.element_at(pick_path_index)
}
# You would iterate the same elements in all_picked.

Returns entity - the entity at the index position in the list of picked entities.

Parameters:

  • index —

    A number from 0 to number of items picked minus one.

Returns:

  • entity - the entity at the index position in the list of picked entities.

Version:

  • SketchUp 6.0

↑ #init(x, y, aperture = 0) ⇒ Sketchup::PickHelper #init(x, y, aperture = 0.0) ⇒ Sketchup::PickHelper

The #init method is used to initialize the PickHelper for testing points.

You do not normally need to call this method, but you can use this if you want to call #test_point or #pick_segment on a lot of points.

Examples:

ph = view.pick_helper
ph.init(x, y, 5)
# Find all points picked by the screen click.
selected = points.select { |point|
  ph.test_point(point)
}

Overloads:

  • #init(x, y, aperture = 0) ⇒ Sketchup::PickHelper
    Note:

    Signature for versions prior to SketchUp 2025.0

    Parameters:

    • x (Integer) —

      Screen coordinate in physical pixels.

    • y (Integer) —

      Screen coordinate in physical pixels.

    • aperture (Integer) (defaults to: 0) —

      The size of the aperture in physical pixels. This is the width and height of the square picking aperture.

    Version:

    • SketchUp 6.0

  • #init(x, y, aperture = 0.0) ⇒ Sketchup::PickHelper

    Parameters:

    • x (Integer) —

      Screen coordinate in logical pixels.

    • y (Integer) —

      Screen coordinate in logical pixels.

    • aperture (Integer) (defaults to: 0.0) —

      The size of the aperture in logical pixels. This is the width and height of the square picking aperture.

    Version:

    • SketchUp 2025.0

Returns:

Version:

  • SketchUp 6.0

↑ #leaf_at(index) ⇒ Object

The leaf_at method retrieves the deepest thing in a pick path.

For example, if you have a face that is within a component that is within another component, leaf_at returns the face.

Use count() to get the number of possible pick paths.

Examples:

pickhelper = view.pick_helper
pickhelper.do_pick(x, y)
# Iterate all pick-routes:
pickhelper.count.times { |pick_path_index|
  p pickhelper.leaf_at(pick_path_index)
}

Returns entity - the leaf entity.

Parameters:

  • index —

    A number from 0 to number of items picked minus one.

Returns:

  • entity - the leaf entity

Version:

  • SketchUp 6.0

↑ #path_at(index) ⇒ Object

The path_at method is used to retrieve the entire path for an entity in the pick list (as an array).

If one of the pick paths end in a face nested in a group nested in a component this method will return an array of these entities. The Group will be first and the face will be last.

The first item in the array will be from the active entities and the last item will be a drawing element that is not a group, component or image.

Examples:

pickhelper = view.pick_helper
pickhelper.do_pick(x, y)
# Iterate all pick-routes:
pickhelper.count.times { |pick_path_index|
  p pickhelper.path_at(pick_path_index)
}

Returns array - an array of entities including the leaf.

Parameters:

  • index —

    A number from 0 to number of items picked minus one.

Returns:

  • array - an array of entities including the leaf

Version:

  • SketchUp 6.0

↑ #pick_segment(points) ⇒ Integer, false #pick_segment(points, x, y, aperture = 0) ⇒ Integer, false

Note:

The return value will be a negative index when a segment is picked.

The #pick_segment method is used to pick a segment of a polyline curve that is defined by an array of points.

If you click on a point in a polyline curve, the index of the point in the curve is returned (starting at 0).

If you click on a segment in the polyline curve, the index of the segment is returned. Segments are returned by negative indicies and start at index -1 (for the segment connecting the first two points) and increase by a factor of -1 (for example, the segment connecting second and third point is -2).

There is no need to invoke #do_pick for this and the results are unrelated.

Examples:

point1 = Geom::Point3d.new(0 ,0, 0)
point2 = Geom::Point3d.new(10, 0, 0)
segment = [point1, point2]
ph = view.pick_helper
# If testing many points this is the fastest way to test.
ph.init(x, y)
picked = ph.pick_segment(segment)
# This do not require .init
picked = ph.pick_segment(segment, x, y)

Overloads:

  • #pick_segment(points) ⇒ Integer, false

    This is more efficient if you need to test a number of segments for the same set of screen coordinates. But then you must use #init first.

    Parameters:

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

      A series of points in the polyline as a list of parameters or an array containing Point3d objects.

    Returns:

    • (Integer, false) —

      an index on success, false on failure

  • #pick_segment(points, x, y, aperture = 0) ⇒ Integer, false

    Returns an index on success, false on failure.

    Parameters:

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

      A series of points in the polyline as a list of parameters or an array containing Point3d objects. Model coordinates.

    • x (Integer) —

      screen mouse position in pixels.

    • y (Integer) —

      (required if x given) screen mouse position in pixels.

    • aperture (defaults to: 0) —

      aperture in pixels.

    Returns:

    • (Integer, false) —

      an index on success, false on failure

Version:

  • SketchUp 6.0

↑ #picked_edge ⇒ Object

The picked_edge method is used to retrieve the “best” Edge picked.

Returns nil if there were no edges picked. You must have called do_pick before calling this method.

Examples:

ph = view.pick_helper
ph.do_pick(x, y)
edge = ph.picked_edge

Returns:

  • edge - an Edge object if successful

Version:

  • SketchUp 6.0

↑ #picked_element ⇒ Sketchup::Drawingelement? #picked_element(index) ⇒ Sketchup::Drawingelement?

The picked_element method retrieves the best drawing element, that is not an edge or a face, picked.

Returns nil if nothing was picked. You must have called do_pick before calling this method.

Examples:

ph = view.pick_helper
ph.do_pick(x, y)
entity = ph.picked_element

Overloads:

Returns:

Version:

  • SketchUp 6.0

↑ #picked_face ⇒ Object

The picked_face method is used to retrieve the best face picked.

Returns nil if there were no faces picked. You must have called do_pick before calling this method.

Examples:

ph = view.pick_helper
ph.do_pick(x, y)
face = ph.picked_face

Returns:

  • face - a Face object if successful

Version:

  • SketchUp 6.0

↑ #test_point(point) ⇒ Boolean #test_point(point, x, y, aperture = 0) ⇒ Boolean

The #test_point method is used to test a point to see if it would be selected using the default or given pick aperture.

There is no need to invoke #do_pick for this and the results are unrelated.

Examples:

ph = view.pick_helper
# If testing many points this is the fastest way to test.
ph.init(x, y)
picked = ph.test_point(point)
# These do not require init()
picked = ph.test_point(point, x, y)
picked = ph.test_point(point, x, y, aperture)

Overloads:

  • #test_point(point) ⇒ Boolean

    This is more efficient if you want to test a lot of points using the same screen point. But you must have called the #init method first for this to work.

    Parameters:

  • #test_point(point, x, y, aperture = 0) ⇒ Boolean

    Parameters:

    • point (Geom::Point3d) —

      Model coordinate.

    • x (Integer) —

      X screen coordinate for the pick.

    • y (Integer) —

      Y screen coordinate for the pick.

    • aperture (Integer) (defaults to: 0) —

      aperture in pixels.

Returns:

  • (Boolean)

See Also:

Version:

  • SketchUp 6.0

↑ #transformation_at(index) ⇒ Object

The transformation_at method is used to get a transformation at a specific pick path index in the pick helper.

The transformation combines the transformation of all groups, components and images in the pick path. This transformation can be used to transform the coordinates of the leaf entity into the coordinates of the active entities.

Examples:

pickhelper = view.pick_helper
pickhelper.do_pick(x, y)
# Iterate all pick-routes:
pickhelper.count.times { |pick_path_index|
  puts pickhelper.transformation_at(pick_path_index)
}

Get transformation for specific picked element

pickhelper = view.pick_helper
pickhelper.do_pick(x, y)
face = pickhelper.picked_face # Face may be inside a group or component.

index = pickhelper.count.times.find { |i| pickhelper.leaf_at(i) == face }
transformation = index ? pickhelper.transformation_at(index) : IDENTITY

# Face#area is one method that may need a transformation.
area = face.area(transformation)

Returns transformation - the transformation found.

Parameters:

  • index —

    The index where the transformation should be retrieved.

Returns:

  • transformation - the transformation found

Version:

  • SketchUp 6.0

↑ #view ⇒ Sketchup::View

The #view method is used to get the view associated with the Sketchup::PickHelper.

Examples:

view = Sketchup.active_model.active_view
ph = view.pick_helper
ph.view

Returns:

Version:

  • SketchUp 6.0

↑ #window_pick(start_point, end_point, pick_type) ⇒ Integer

Note:

Prior to SketchUp 2025.0 this method expected physical screen coordinates. As of SketchUp 2025.0 they are expected to be logical screen coordinates.

Used to pick a set of entities from a model based on a screen coordinate rectangular area defined by two points. The pick criteria can be for completely-contained or partially-contained entities, similar to how the Selection tool works. The z value of the points passed in are ignored.

Examples:

ph = Sketchup.active_model.active_view.pick_helper
start_point = Geom::Point3d.new(100, 100, 0)
end_point = Geom::Point3d.new(500, 500, 0)
num_picked = ph.window_pick(start_point, end_point, Sketchup::PickHelper::PICK_CROSSING)
picked_entities = ph.all_picked

Returns The number of Drawingelement objects picked.

Parameters:

  • start_point (Geom::Point3d) —

    First screen coordinate point.

  • end_point (Geom::Point3d) —

    Second screen coordinate point.

  • pick_type (Integer) —

    PICK_INSIDE to select entities completely contained or PICK_CROSSING to select entities partially contained.

Returns:

Version:

  • SketchUp 2016