# The SketchUp Array class adds additional methods to the standard Ruby Array # class. Specifically, it contains methods allowing an array to behave just as a # {Geom::Vector3d} or {Geom::Point3d} object (which can be thought of as arrays # of 3 coordinate values). Therefore, you can use the Array class in place of a # {Geom::Point3d} or {Geom::Vector3d} as a way to pass coordinate values. # # In addition to the built-in {http://www.ruby-doc.org/core-2.0.0/Array.html Ruby Array} # methods, the following methods have been added by SketchUp. # # @note In SketchUp, Arrays may be used in place of either {Geom::Point3d} and # {Geom::Vector3d} objects depending on how they are used. # # @example # # An array of 3 values can represent a 1" long vector pointing straight # # up in the z-direction. # array = [0, 0, 1] # # # An array of 3 values can also represent a point 1" above the origin in # # the z direction. (Note that this is the exact same array.) # array = [0, 0, 1] # # # How it is interpreted is based on context. For example, this code will # # create a construction point at position 0, 0, 1, since in this context # # a Point3d is expected. # entities = Sketchup.active_model.entities # construction_point = entities.add_cpoint(array) # # # Whereas this will move our construction point 1" upward, since in this # # context a Vector3d is expected. # transformation = Geom::Transformation.new(array) # entities.transform_entities(transformation, construction_point) # # @see http://www.sketchup.com/intl/en/developer/docs/ourdoc/array Array Docs # # @since SketchUp 6.0 class Array # Compute the cross product between two vectors, particularly this vector and # the given vector. # # @example # vector1 = Geom::Vector3d.new(0, 1, 0) # array = [1, 0, 0] # This will return a new Vector3d # vector2 = array.cross(vector1) # # @param [Geom::Vector3d, Array<Numeric>] vector # # @return [Vector3d] Computed cross product. def cross(vector) end # Compute the distance between this point and the given point. # # @example # [0,0].distance([1,1]) # ==> 1.414 # ORIGIN.distance([1,1,1]) # ==> 1.732 # # @example # point = Geom::Point3d.new(10, 10, 10) # array = [1, 1, 1] # # This will return a Length # distance = array.distance(point) # # @param [Geom::Point3d, Array<Numeric>] point # # @return [Length] Computed distance. def distance(point) end # Compute the distance from the current point to a line. Lines are defined by # an array of a point and a vector or an array of two points. See the {Geom} # module for instructions on how to create a line. # # @example # line = [Geom::Point3d.new(0, 0, 0), Geom::Vector3d.new(0, 0, 1)] # array = [10, 10, 10] # # This will return a Length # distance = array.distance_to_line(line) # # @param [Array<(Geom::Point3d, Geom::Vector3d)>, Array<(Geom::Point3d, Geom::Point3d)>] line # An array with a {Geom::Point3d} object and a {Geom::Vector3d} object or an # array with two {Geom::Point3d} objects representing the line. # # @return [Length] Computed distance. def distance_to_line(line) end # Compute the distance from the current point to a plane. See the {Geom} # module for instructions on how to create a plane. # # @example # plane = [Geom::Point3d.new(0, 0, 0), Geom::Vector3d.new(0, 0, 1)] # array = [10, 10, 10] # # This will return a Length # distance = array.distance_to_plane(plane) # # @param [Array<(Geom::Point3d, Geom::Vector3d)>] plane An array with a # {Geom::Point3d} object and a {Geom::Vector3d} object representing the # plane. # # @return [Length] Computed distance. def distance_to_plane(plane) end # Compute the dot product between the current and the specified vector. # # @example # [0, 0, 1].dot([0, 1, 0]) # ==> 0.0 # # @example # vector = Geom::Vector3d.new(0, 1, 0) # array = [1, 0, 0] # # This will return a Float, in this case 22.0 # dot_product = array.dot(vector) # # @param [Vector3d] vector # # @return [Float] Computed dot product. def dot(vector) end # Normalize the current vector (setting its length to one). It returns a new # array rather than changing the original in place. # # @example # array = [1, 2, 3] # # This will return a new Array # normal_vector = array.normalize # # @return [Array] A new array representing the normalized vector. def normalize end # Normalize the current vector in place (settings its length to one). # # @example # array = [1, 2, 3] # # This will modify the 'array' in place. # normal_vector = array.normalize! # # @return [Array] The current array with the normalized vector. def normalize! end # Offset current point by a vector. This returns a new array rather than # modifying the original in place. # # @example # array = [10, 10, 10] # vector = Geom::Vector3d.new(0, 0, 1) # # This will return a new Array # point = array.offset(vector) # # @param [Geom::Vector3d, Array<Numeric>] vector # # @return [Array] The newly offset array. def offset(vector) end # Offset current point by a vector in place. This modifies the current array. # # @example # array = [10, 10, 10] # vector = Geom::Vector3d.new(0, 0, 1) # # This will modify 'array' in place. # point = array.offset!(vector) # # @param [Geom::Vector3d, Array<Numeric>] vector # # @return [Array] The current offset array. def offset!(vector) end # Determine if the current point is on the given line. See the {Geom} module # for instructions on how to create a line. # # @example # line = [Geom::Point3d.new(0, 0, 0), Geom::Vector3d.new(0, 0, 1)] # array = [10, 10, 10] # # This will return a true or false value # on_plane = array.on_line?(line) # # @param [Array<(Geom::Point3d, Geom::Vector3d)>, Array<(Geom::Point3d, Geom::Point3d)>] line # An array with a {Geom::Point3d} object and a {Geom::Vector3d} object or an # array with two {Geom::Point3d} objects representing the line. # # @return [Boolean] +true+ if the point is on the line or +false+ if the point # is not on the line. def on_line?(line) end # Determine if the current point is on the given plane. See the {Geom} module # for instructions on how to create a plane. # # @example # plane = [Geom::Point3d.new(0, 0, 0), Geom::Vector3d.new(0, 0, 1)] # array = [10, 10, 10] # # This will return false because the current point is not on the plane. # on_plane = array.on_plane?(plane) # # @param [Array<(Geom::Point3d, Geom::Vector3d)>] plane An array with a # {Geom::Point3d} object and a {Geom::Vector3d} object representing the # plane. # # @return [Boolean] +true+ if the point is on the plane or +false+ if the # point is not on the plane. def on_plane?(plane) end # Project point onto a line. See the {Geom} module for instructions on how to # create a line. # # @example # line = [Geom::Point3d.new(0, 0, 0), Geom::Vector3d.new(0, 0, 1)] # array = [10, 10, 10] # # This will return a new Array # point_on_line = array.project_to_line(line) # # @param [Array<(Geom::Point3d, Geom::Vector3d)>, Array<(Geom::Point3d, Geom::Point3d)>] line # An array with a {Geom::Point3d} object and a {Geom::Vector3d} object or an # array with two {Geom::Point3d} objects representing the line. # # @return [Array] A new point on the line that is closest to this point if # successful. def project_to_line(line) end # Project point onto a plane. See the {Geom} module for instructions on how to # create a plane. # # @example # plane = [Geom::Point3d.new(0, 0, 0), Geom::Vector3d.new(0, 0, 1)] # array = [10, 10, 10] # # This will return a new Array # point_on_line = array.project_to_plane(plane) # # @param [Array<(Geom::Point3d, Geom::Vector3d)>] plane An array with a # {Geom::Point3d} object and a {Geom::Vector3d} object representing the # plane. # # @return [Array] A new point on the plane that is closest to this point if # successful. def project_to_plane(plane) end # Apply {Geom::Transformation} object to the current point defined by an # {Array} object. This method returns a new transformed point rather than # modifying the current point. # # @example # point = Geom::Point3d.new(10, 20, 30) # transform = Geom::Transformation.new(point) # array = [1, 2, 3] # # This will return a new Array # array.transform(transform) # # @param [Geom::Transformation] transformation # # @return [Array] The newly transformed point. def transform(transformation) end # Apply {Geom::Transformation} object to the current point defined by an # {Array} object. This method modifies the current point. # # @example # point = Geom::Point3d.new(10, 20, 30) # transform = Geom::Transformation.new(point) # array = [1, 2, 3] # # This will modify 'array' in place # array.transform!(transform) # # @param [Geom::Transformation] transformation # # @return [Array] The current transformed point. def transform!(transformation) end # Compute vector from the current point to the given point. # # @example # point = Geom::Point3d.new(10, 20, 30) # array = [1, 2, 3] # # This will return a new Vector3d # vector = array.vector_to(point) # # @param [Geom::Point3d, Array<Numeric>] point # # @return [Geom::Vector3d] def vector_to(point) end # Get the X coordinate or the first element of the array. # # @example # [1, 2, 3].x # ==> 1 # # @example # array = [1, 2, 3] # # This will return a Fixnum, in this case 1 # x = array.x # # array = [1.0, 2.0, 3.0] # # This will return a Float, in this case 1.0 # x = array.x # # @return [Numeric] The X coordinate or the first element. def x end # Set the X coordinate or the first element of the array. # # @example # array = [1, 2, 3] # # This will initialize the x value as a Float # array.x = 2.5 # # This will initialize the x value as a Fixnum # array.x = 5 # # @return [Object] The newly assigned value. def x= end # Get the Y coordinate or the second element of the array. # # @example # [1, 2, 3].y # ==> 2 # # @example # array = [1, 2, 3] # # This will return a Fixnum, in this case 2 # y = array.y # # array = [1.0, 2.0, 3.0] # # This will return a Float, in this case 2.0 # y = array.y # # @return [Numeric] The Y coordinate or the second element. def y end # Set the Y coordinate or the second element of the array. # # @example # array = [1, 2, 3] # # This will initialize the y value as a Float # array.y = 2.5 # # This will initialize the y value as a Fixnum # array.y = 5 # # @return [Object] The newly assigned value. def y= end # Get the Z coordinate or the third element of the array. # # @example # [1, 2, 3].z # ==> 2 # # @example # array = [1, 2, 3] # # This will return a Fixnum, in this case 3 # z = array.z # # array = [1.0, 2.0, 3.0] # # This will return a Float, in this case 3.0 # z = array.z # # @return [Numeric] The Z coordinate or the third element. def z end # Set the Z coordinate or the third element of the array. # # @example # array = [1, 2, 3] # # This will initialize the z value as a Float # array.z = 2.5 # # This will initialize the z value as a Fixnum # array.z = 5 # # @return [Object] The newly assigned value. def z= end end # class Array