referenceframe

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 20, 2022 License: AGPL-3.0 Imports: 19 Imported by: 7

Documentation

Overview

Package referenceframe defines the api and does the math of translating between reference frames Useful for if you have a camera, connected to a gripper, connected to an arm, and need to translate the camera reference frame to the arm reference frame, if you've found something in the camera, and want to move the gripper + arm to get it.

Index

Constants

View Source 
const OOBErrString = "input out of bounds"

OOBErrString is a string that all OOB errors should contain, so that they can be checked for distinct from other Transform errors.

View Source 
const World = "world"

World is the string "world", but made into an exported constant.

Variables

View Source 
var ErrNoModelInformation = errors.New("no model information")

ErrNoModelInformation is used when there is no model information.

Functions

func GenerateRandomConfiguration 

func GenerateRandomConfiguration(m Model, randSeed *rand.Rand) []float64

GenerateRandomConfiguration generates a list of radian joint positions that are random but valid for each joint.

func GeometriesInFrameToProtobuf 

func GeometriesInFrameToProtobuf(framedGeometries *GeometriesInFrame) *commonpb.GeometriesInFrame

GeometriesInFrameToProtobuf converts a GeometriesInFrame struct to a GeometriesInFrame message as specified in common.proto.

func InputsToFloats 

func InputsToFloats(inputs []Input) []float64

InputsToFloats unwraps Inputs to raw floats.

func IsConfigurationValid 

func IsConfigurationValid(m Model, configuration []float64) bool

IsConfigurationValid checks whether the given array of joint positions violates any joint limits.

func JointPositionsFromRadians 

func JointPositionsFromRadians(radians []float64) *pb.JointPositions

JointPositionsFromRadians converts the given slice of radians into joint positions (represented in degrees).

func JointPositionsToRadians 

func JointPositionsToRadians(jp *pb.JointPositions) []float64

JointPositionsToRadians converts the given positions into a slice of radians.

func NewFrameAlreadyExistsError added in v0.1.0 

func NewFrameAlreadyExistsError(frameName string) error

NewFrameAlreadyExistsError returns an error indicating that a frame of the given name already exists.

func NewFrameMissingError added in v0.1.0 

func NewFrameMissingError(frameName string) error

NewFrameMissingError returns an error indicating that the given frame is missing from the framesystem.

func NewIncorrectInputLengthError added in v0.1.0 

func NewIncorrectInputLengthError(actual, expected int) error

NewIncorrectInputLengthError returns an error indicating that the length of the Innput array does not match the DoF of the frame.

func NewParentFrameMissingError 

func NewParentFrameMissingError() error

NewParentFrameMissingError returns an error indicating that the parent frame is nil.

func PoseInFrameToProtobuf 

func PoseInFrameToProtobuf(framedPose *PoseInFrame) *commonpb.PoseInFrame

PoseInFrameToProtobuf converts a PoseInFrame struct to a PoseInFrame message as specified in common.proto.

func StartPositions 

func StartPositions(fs FrameSystem) map[string][]Input

StartPositions returns a zeroed input map ensuring all frames have inputs.

Types

type Frame 

type Frame interface {
	// Name returns the name of the referenceframe.
	Name() string

	// Transform is the pose (rotation and translation) that goes FROM current frame TO parent's referenceframe.
	Transform([]Input) (spatial.Pose, error)

	// Geometries returns a map between names and geometries for the reference frame and any intermediate frames that
	// may be defined for it, e.g. links in an arm. If a frame does not have a geometryCreator it will not be added into the map
	Geometries([]Input) (*GeometriesInFrame, error)

	// DoF will return a slice with length equal to the number of joints/degrees of freedom.
	// Each element describes the min and max movement limit of that joint/degree of freedom.
	// For robot parts that don't move, it returns an empty slice.
	DoF() []Limit

	// AlmostEquals returns if the otherFrame is close to the referenceframe.
	// differences should just be things like floating point inprecision
	AlmostEquals(otherFrame Frame) bool

	// InputFromProtobuf does there correct thing for this frame to convert protobuf units (degrees/mm) to input units (radians/mm)
	InputFromProtobuf(*pb.JointPositions) []Input

	// ProtobufFromInput does there correct thing for this frame to convert input units (radians/mm) to protobuf units (degrees/mm)
	ProtobufFromInput([]Input) *pb.JointPositions

	json.Marshaler
}

Frame represents a reference frame, e.g. an arm, a joint, a gripper, a board, etc.

func FrameFromPoint 

func FrameFromPoint(name string, point r3.Vector) (Frame, error)

FrameFromPoint creates a new Frame from a 3D point.

func NewMobile2DFrame 

func NewMobile2DFrame(name string, limit []Limit, geometryCreator spatial.GeometryCreator) (Frame, error)

NewMobile2DFrame instantiates a frame that can translate in the x and y dimensions and will always remain on the plane Z=0 This frame will have a name, limits (representing the bounds the frame is allowed to translate within) and a geometryCreator defined by the arguments passed into this function.

func NewRotationalFrame 

func NewRotationalFrame(name string, axis spatial.R4AA, limit Limit) (Frame, error)

NewRotationalFrame creates a new rotationalFrame struct. A standard revolute joint will have 1 DoF.

func NewStaticFrame 

func NewStaticFrame(name string, pose spatial.Pose) (Frame, error)

NewStaticFrame creates a frame given a pose relative to its parent. The pose is fixed for all time. Pose is not allowed to be nil.

func NewStaticFrameFromFrame 

func NewStaticFrameFromFrame(frame Frame, pose spatial.Pose) (Frame, error)

NewStaticFrameFromFrame creates a frame given a pose relative to its parent. The pose is fixed for all time. It inherits its name and geometryCreator properties from the specified Frame. Pose is not allowed to be nil.

func NewStaticFrameWithGeometry 

func NewStaticFrameWithGeometry(name string, pose spatial.Pose, geometryCreator spatial.GeometryCreator) (Frame, error)

NewStaticFrameWithGeometry creates a frame given a pose relative to its parent. The pose is fixed for all time. It also has an associated geometryCreator representing the space that it occupies in 3D space. Pose is not allowed to be nil.

func NewTranslationalFrame 

func NewTranslationalFrame(name string, axis r3.Vector, limit Limit) (Frame, error)

NewTranslationalFrame creates a frame given a name and the axis in which to translate.

func NewTranslationalFrameWithGeometry 

func NewTranslationalFrameWithGeometry(name string, axis r3.Vector, limit Limit, geometryCreator spatial.GeometryCreator) (Frame, error)

NewTranslationalFrameWithGeometry creates a frame given a given a name and the axis in which to translate. It also has an associated geometryCreator representing the space that it occupies in 3D space. Pose is not allowed to be nil.

func NewZeroStaticFrame 

func NewZeroStaticFrame(name string) Frame

NewZeroStaticFrame creates a frame with no translation or orientation changes.

func UnmarshalFrameJSON 

func UnmarshalFrameJSON(data []byte) (Frame, error)

UnmarshalFrameJSON deserialized json into a reference referenceframe.

type FrameMapConfig 

type FrameMapConfig map[string]interface{}

FrameMapConfig represents the format for configuring a Frame object.

func (FrameMapConfig) ParseConfig 

func (config FrameMapConfig) ParseConfig() (Frame, error)

ParseConfig converts a FrameMapConfig to a Frame object.

type FrameSystem 

type FrameSystem interface {
	// Name returns the name of this FrameSystem
	Name() string

	// World returns the frame corresponding to the root of the FrameSystem, from which other frames are defined with respect to
	World() Frame

	// FrameNames returns the names of all of the frames that exist in the FrameSystem
	FrameNames() []string

	// Frame returns the Frame in the FrameSystem corresponding to
	Frame(name string) Frame

	// AddFrame inserts a given Frame into the FrameSystem as a child of the parent Frame
	AddFrame(frame, parent Frame) error

	// RemoveFrame removes the given Frame from the FrameSystem
	RemoveFrame(frame Frame)

	// TracebackFrame traces the parentage of the given frame up to the world, and returns the full list of frames in between.
	// The list will include both the query frame and the world referenceframe
	TracebackFrame(frame Frame) ([]Frame, error)

	// Parent returns the parent Frame for the given Frame in the FrameSystem
	Parent(frame Frame) (Frame, error)

	// Transform takes in a Transformable object and destination frame, and returns the pose from the first to the second. Positions
	// is a map of inputs for any frames with non-zero DOF, with slices of inputs keyed to the frame name.
	Transform(positions map[string][]Input, object Transformable, dst string) (Transformable, error)

	// FrameSystemSubset will take a frame system and a frame in that system, and return a new frame system rooted
	// at the given frame and containing all descendents of it. The original frame system is unchanged.
	FrameSystemSubset(newRoot Frame) (FrameSystem, error)

	// DivideFrameSystem will take a frame system and a frame in that system, and return a new frame system rooted
	// at the given frame and containing all descendents of it, while the original has the frame and its
	// descendents removed.
	DivideFrameSystem(newRoot Frame) (FrameSystem, error)

	// MergeFrameSystem combines two frame systems together, placing the world of systemToMerge at the attachTo frame in the frame system
	MergeFrameSystem(systemToMerge FrameSystem, attachTo Frame) error
}

FrameSystem represents a tree of frames connected to each other, allowing for transformations between any two frames.

func NewEmptySimpleFrameSystem 

func NewEmptySimpleFrameSystem(name string) FrameSystem

NewEmptySimpleFrameSystem creates a graph of Frames that have.

type GeometriesInFrame 

type GeometriesInFrame struct {
	// contains filtered or unexported fields
}

GeometriesInFrame is a data structure that packages geometries with the name of the frame in which it was observed.

func NewGeometriesInFrame 

func NewGeometriesInFrame(frame string, geometries map[string]spatialmath.Geometry) *GeometriesInFrame

NewGeometriesInFrame generates a new GeometriesInFrame.

func ProtobufToGeometriesInFrame 

func ProtobufToGeometriesInFrame(proto *commonpb.GeometriesInFrame) (*GeometriesInFrame, error)

ProtobufToGeometriesInFrame converts a GeometriesInFrame message as specified in common.proto to a GeometriesInFrame struct.

func (*GeometriesInFrame) FrameName 

func (gF *GeometriesInFrame) FrameName() string

FrameName returns the name of the frame in which the geometries were observed.

func (*GeometriesInFrame) Geometries 

func (gF *GeometriesInFrame) Geometries() map[string]spatialmath.Geometry

Geometries returns the geometries observed.

func (*GeometriesInFrame) Transform 

func (gF *GeometriesInFrame) Transform(tf *PoseInFrame) Transformable

Transform changes the GeometriesInFrame gF into the reference frame specified by the tf argument. The tf PoseInFrame represents the pose of the gF reference frame with respect to the destination reference frame.

type Input 

type Input struct {
	Value float64
}

Input wraps the input to a mutable frame, e.g. a joint angle or a gantry position. Revolute inputs should be in radians. Prismatic inputs should be in mm. TODO: Determine what more this needs, or eschew in favor of raw float64s if nothing needed.

func FloatsToInputs 

func FloatsToInputs(floats []float64) []Input

FloatsToInputs wraps a slice of floats in Inputs.

func GetFrameInputs 

func GetFrameInputs(frame Frame, inputMap map[string][]Input) ([]Input, error)

GetFrameInputs looks through the inputMap and returns a slice of Inputs corresponding to the given frame.

func InterpolateInputs 

func InterpolateInputs(from, to []Input, by float64) []Input

InterpolateInputs will return a set of inputs that are the specified percent between the two given sets of inputs. For example, setting by to 0.5 will return the inputs halfway between the from/to values, and 0.25 would return one quarter of the way from "from" to "to".

func RandomFrameInputs 

func RandomFrameInputs(m Frame, rSeed *rand.Rand) []Input

RandomFrameInputs will produce a list of valid, in-bounds inputs for the referenceframe.

func RestrictedRandomFrameInputs 

func RestrictedRandomFrameInputs(m Frame, rSeed *rand.Rand, lim float64) []Input

RestrictedRandomFrameInputs will produce a list of valid, in-bounds inputs for the frame, restricting the range to `lim` percent of the limits.

type InputEnabled 

type InputEnabled interface {
	CurrentInputs(ctx context.Context) ([]Input, error)
	GoToInputs(ctx context.Context, goal []Input) error
}

InputEnabled is a standard interface for all things that interact with the frame system This allows us to figure out where they currently are, and then move them. Input units are always in meters or radians.

type Limit 

type Limit struct {
	Min float64
	Max float64
}

Limit represents the limits of motion for a referenceframe.

type Model 

type Model interface {
	Frame
	ChangeName(string)
}

A Model represents a frame that can change its name.

func ParseModelJSONFile 

func ParseModelJSONFile(filename, modelName string) (Model, error)

ParseModelJSONFile will read a given file and then parse the contained JSON data.

func UnmarshalModelJSON 

func UnmarshalModelJSON(jsonData []byte, modelName string) (Model, error)

UnmarshalModelJSON will parse the given JSON data into a kinematics model. modelName sets the name of the model, will use the name from the JSON if string is empty.

type ModelConfig 

type ModelConfig struct {
	Name         string `json:"name"`
	KinParamType string `json:"kinematic_param_type"`
	Links        []struct {
		ID          string                    `json:"id"`
		Parent      string                    `json:"parent"`
		Translation spatial.TranslationConfig `json:"translation"`
		Orientation spatial.OrientationConfig `json:"orientation"`
		Geometry    spatial.GeometryConfig    `json:"geometry"`
	} `json:"links"`
	Joints []struct {
		ID     string             `json:"id"`
		Type   string             `json:"type"`
		Parent string             `json:"parent"`
		Axis   spatial.AxisConfig `json:"axis"`
		Max    float64            `json:"max"`
		Min    float64            `json:"min"`
	} `json:"joints"`
	DHParams []struct {
		ID       string                 `json:"id"`
		Parent   string                 `json:"parent"`
		A        float64                `json:"a"`
		D        float64                `json:"d"`
		Alpha    float64                `json:"alpha"`
		Max      float64                `json:"max"`
		Min      float64                `json:"min"`
		Geometry spatial.GeometryConfig `json:"geometry"`
	} `json:"dhParams"`
	RawFrames []FrameMapConfig `json:"frames"`
}

ModelConfig represents all supported fields in a kinematics JSON file.

func (*ModelConfig) ParseConfig 

func (config *ModelConfig) ParseConfig(modelName string) (Model, error)

ParseConfig converts the ModelConfig struct into a full Model with the name modelName.

type ModelFramer 

type ModelFramer interface {
	ModelFrame() Model
}

ModelFramer has a method that returns the kinematics information needed to build a dynamic referenceframe.

type PoseInFrame 

type PoseInFrame struct {
	// contains filtered or unexported fields
}

PoseInFrame is a data structure that packages a pose with the name of the frame in which it was observed.

func NewPoseInFrame 

func NewPoseInFrame(frame string, pose spatialmath.Pose) *PoseInFrame

NewPoseInFrame generates a new PoseInFrame.

func ProtobufToPoseInFrame 

func ProtobufToPoseInFrame(proto *commonpb.PoseInFrame) *PoseInFrame

ProtobufToPoseInFrame converts a PoseInFrame message as specified in common.proto to a PoseInFrame struct.

func (*PoseInFrame) FrameName 

func (pF *PoseInFrame) FrameName() string

FrameName returns the name of the frame in which the pose was observed.

func (*PoseInFrame) Pose 

func (pF *PoseInFrame) Pose() spatialmath.Pose

Pose returns the pose that was observed.

func (*PoseInFrame) Transform 

func (pF *PoseInFrame) Transform(tf *PoseInFrame) Transformable

Transform changes the PoseInFrame pF into the reference frame specified by the tf argument. The tf PoseInFrame represents the pose of the pF reference frame with respect to the destination reference frame.

type SimpleModel 

type SimpleModel struct {

	// OrdTransforms is the list of transforms ordered from end effector to base
	OrdTransforms []Frame
	// contains filtered or unexported fields
}

SimpleModel TODO.

func NewSimpleModel 

func NewSimpleModel() *SimpleModel

NewSimpleModel constructs a new model.

func (*SimpleModel) AlmostEquals 

func (m *SimpleModel) AlmostEquals(otherFrame Frame) bool

AlmostEquals returns true if the only difference between this model and another is floating point inprecision.

func (*SimpleModel) CachedTransform 

func (m *SimpleModel) CachedTransform(inputs []Input) (spatialmath.Pose, error)

CachedTransform will check a sync.Map cache to see if the exact given set of inputs has been computed yet. If so it returns without redoing the calculation. Thread safe, but so far has tended to be slightly slower than just doing the calculation. This may change with higher DOF models and longer runtimes.

func (*SimpleModel) ChangeName 

func (m *SimpleModel) ChangeName(name string)

ChangeName changes the name of this model - necessary for building frame systems.

func (*SimpleModel) DoF 

func (m *SimpleModel) DoF() []Limit

DoF returns the number of degrees of freedom within a model.

func (*SimpleModel) Geometries 

func (m *SimpleModel) Geometries(inputs []Input) (*GeometriesInFrame, error)

Geometries returns an object representing the 3D space associeted with the staticFrame.

func (*SimpleModel) InputFromProtobuf 

func (m *SimpleModel) InputFromProtobuf(jp *pb.JointPositions) []Input

InputFromProtobuf converts pb.JointPosition to inputs.

func (*SimpleModel) MarshalJSON 

func (m *SimpleModel) MarshalJSON() ([]byte, error)

MarshalJSON serializes a Model.

func (*SimpleModel) Name 

func (m *SimpleModel) Name() string

Name returns the name of this model.

func (*SimpleModel) OperationalDoF 

func (m *SimpleModel) OperationalDoF() int

OperationalDoF returns the number of end effectors. Currently we only support one end effector but will support more.

func (*SimpleModel) ProtobufFromInput 

func (m *SimpleModel) ProtobufFromInput(input []Input) *pb.JointPositions

ProtobufFromInput converts inputs to pb.JointPosition.

func (*SimpleModel) Transform 

func (m *SimpleModel) Transform(inputs []Input) (spatialmath.Pose, error)

Transform takes a model and a list of joint angles in radians and computes the dual quaternion representing the cartesian position of the end effector. This is useful for when conversions between quaternions and OV are not needed.

type Transformable 

type Transformable interface {
	Transform(*PoseInFrame) Transformable
	FrameName() string
}

Transformable is an interface to describe elements that can be transformed by the frame system.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.