vkf_frames – vkframes

Reference frames: the tree of frames that every scene object belongs to, as OpenFrames' ReferenceFrame.

A frame has a position and attitude relative to its parent, a color for its decorations (axes, labels), and children. It can follow trajectories (follow), which then set its position and/or attitude at each update. Scene objects (spheres, models, trajectories' artists, ...) extend this type.

Frames are owned by the program, not by the tree: add_child stores pointers, so a frame (declared target, or allocated) must stay alive while it is in a tree, or be removed first (detach). A frame may have several parents; adding a child that is an ancestor of the parent is refused.

Rendering: when a window first shows a tree (realize), each frame gets a transform node, with its contents (build_contents, which extensions override) under a switch for show_contents; children's nodes go under the parent's transform, so a frame with several parents is drawn under each. Poses at any time (world_matrix_at): a frame's transform to the root at a time other than the current one, from what moves it: its fixed position and attitude, and the trajectories it follows (their state at that time, state_at). A frame the program moves (sets its position each frame) has no history: its current pose is used for every time. Trajectories drawn in a frame other than the one their data are in (DrawableTrajectory's set_data_frame) use these, each point at its own time; motion_key tells them when a frame's motion changed (its pose set, its parents, what it follows and how, the followed data).

Each frame, update moves followed frames to the time, then late_update lets contents depend on other frames' positions at that time (e.g. CustomLineSegments between spacecraft), and sync copies positions and attitudes to the transforms. A shown tree can change: children added to a shown frame are realized and compiled (for the windows running) and drawn from the next frame; removed ones stop being drawn; moved axes (move_x_axis, ...) are made again.

Labels: the name label (at the origin, facing the screen) and the axes' labels can change while shown: the name (set_name, e.g. a readout that follows the frame), color, label size, alignment and font, and the axes' label texts.

Picking (pick): each frame tests what it draws against a PickCamera (vkf_pick) in its pick procedure, given its transform to the root frame, and adds a PickHit for each thing within reach (the window sorts them nearest first). A plain frame is picked at its origin if it shows axes or its name label (PICK_FRAME); extensions pick their contents (bodies, trajectories).

Uses

Help

Graph Key

Nodes of different colours represent the following:

Solid arrows point from a submodule to the (sub)module which it is descended from. Dashed arrows point from a module or program unit to modules which it uses.

Used by

Help

Graph Key

Nodes of different colours represent the following:

Solid arrows point from a submodule to the (sub)module which it is descended from. Dashed arrows point from a module or program unit to modules which it uses.

Variables

Type	Visibility	Attributes		Name		Initial
integer,	public,	parameter	::	ALIGN_CENTER_BASE_LINE	=	10
integer,	public,	parameter	::	ALIGN_CENTER_BOTTOM	=	5
integer,	public,	parameter	::	ALIGN_CENTER_CENTER	=	4
integer,	public,	parameter	::	ALIGN_CENTER_TOP	=	3
integer,	public,	parameter	::	ALIGN_LEFT_BASE_LINE	=	9
integer,	public,	parameter	::	ALIGN_LEFT_BOTTOM	=	2	text alignment of labels (osgText's AlignmentType, as OpenFrames uses)
integer,	public,	parameter	::	ALIGN_LEFT_CENTER	=	1	text alignment of labels (osgText's AlignmentType, as OpenFrames uses)
integer,	public,	parameter	::	ALIGN_LEFT_TOP	=	0	text alignment of labels (osgText's AlignmentType, as OpenFrames uses)
integer,	public,	parameter	::	ALIGN_RIGHT_BASE_LINE	=	11
integer,	public,	parameter	::	ALIGN_RIGHT_BOTTOM	=	8
integer,	public,	parameter	::	ALIGN_RIGHT_CENTER	=	7
integer,	public,	parameter	::	ALIGN_RIGHT_TOP	=	6
integer,	public,	parameter	::	ALL_AXES	=	7	all three
integer,	public,	parameter	::	NO_AXES	=	0	which axes to show (OpenFrames' AxesType), combined with ior none
integer,	public,	parameter	::	PICK_BODY	=	2	a body's surface (Sphere, Model, TerrainBody)
integer,	public,	parameter	::	PICK_CURVE	=	3	a trajectory's curve (CurveArtist)
integer,	public,	parameter	::	PICK_FRAME	=	1	what a pick hit (PickHit%kind) a frame's origin (its axes or name label shown)
integer,	public,	parameter	::	PICK_HANDLE	=	6	a handle the mouse drags (vkf_handles: VectorHandle)
integer,	public,	parameter	::	PICK_MARKER	=	5	a trajectory's marker (MarkerArtist)
integer,	public,	parameter	::	PICK_SEGMENT	=	4	a trajectory's segment (SegmentArtist)
integer,	public,	parameter	::	X_AXIS	=	1	the x axis
integer,	public,	parameter	::	Y_AXIS	=	2	the y axis
integer,	public,	parameter	::	Z_AXIS	=	4	the z axis

Interfaces

public interface ReferenceFrame

The ReferenceFrame constructor: ReferenceFrame(...) makes one (see new_reference_frame for its arguments).

private function new_reference_frame(name, color) result(frame)

A frame named name, with decorations of color color ([r, g, b] or [r, g, b, a], 0 to 1; default white, 90% opaque).

Arguments

Type	Intent	Optional	Attributes		Name
character(len=*),	intent(in)			::	name	the frame's name (shown by its name label)
real(kind=wp),	intent(in),	optional		::	color(:)	[r, g, b] or [r, g, b, a] (0 to 1; default white, 90% opaque)

Return Value type(ReferenceFrame)

Derived Types

type, public :: FramePointer

A frame in a list of frames (a frame's children and parents): a pointer to it (Fortran has no arrays of pointers).

Components

Type	Visibility	Attributes		Name		Initial
class(ReferenceFrame),	public,	pointer	::	p	=>	null()	the frame (not owned)

type, public :: PickHit

What a pick found (pick): the frame it belongs to and, for trajectories, the artist (select type to use it) and the trajectory.

Components

Type	Visibility	Attributes		Name		Initial
class(*),	public,	pointer	::	artist	=>	null()	the trajectory artist (curves, segments, markers)
real(kind=wp),	public		::	distance	=	0.0_wp	its depth from the eye (nearest first)
class(ReferenceFrame),	public,	pointer	::	frame	=>	null()	the frame hit (what it draws, or its origin)
integer,	public		::	index	=	0	For curves, the trajectory point the hit is after (on the segment from it to the next); segments: the segment (from point 1 + (index - 1) * stride); markers: the point (start, end) or the intermediate marker's number
integer,	public		::	kind	=	0	PICK_*
real(kind=wp),	public		::	latitude	=	0.0_wp	(bodies: geodetic, radians (Sphere, TerrainBody))
real(kind=wp),	public		::	local(3)	=	0.0_wp	the point hit, in the frame's coordinates
real(kind=wp),	public		::	longitude	=	0.0_wp	(bodies: geodetic, radians (Sphere, TerrainBody))
integer,	public		::	marker	=	0	(markers: MARKER_START, MARKER_END or MARKER_INTERMEDIATE)
real(kind=wp),	public		::	pixels	=	0.0_wp	its distance from the cursor (framebuffer pixels; 0 on a body)
real(kind=wp),	public		::	position(3)	=	0.0_wp	the point hit, in the root frame
real(kind=wp),	public		::	time	=	0.0_wp	(trajectories: the time there (interpolated on curves))
type(Trajectory),	public,	pointer	::	trajectory	=>	null()	(trajectories: the artist's trajectory)

type, public :: ReferenceFrame

A reference frame (see the module documentation).

Components

Type	Visibility	Attributes		Name		Initial
real(kind=wp),	private		::	attitude_(4)	=	quat_identity	relative to the parent: quaternion [x, y, z, w]
integer,	private		::	axes	=	ALL_AXES	OpenFrames' defaults: all shown
integer,	private		::	axes_labels	=	ALL_AXES	axes labels shown (as axes)
logical,	private		::	axes_moved	=	.false.	set by move_*_axis (else reposition_axes places them)
type(c_ptr),	private		::	axis_arrow(3)	=	c_null_ptr	the axes arrows (in axis_node; made again when an axis moves)
real(kind=wp),	private		::	axis_base(3,3)	=	0.0_wp	each axis's base (columns; frame coordinates)
real(kind=wp),	private		::	axis_body_radius(3)	=	0.0_wp	(0: 0.05 and 0.1 of the length)
real(kind=wp),	private		::	axis_head_radius(3)	=	0.0_wp	(0: 0.05 and 0.1 of the length)
real(kind=wp),	private		::	axis_head_ratio(3)	=	0.3_wp	each axis's head, as a fraction of its length
type(c_ptr),	private		::	axis_label_node(3)	=	c_null_ptr	the axes labels' switches
real(kind=wp),	private		::	axis_len(3)	=	1.0_wp	each axis's length
type(c_ptr),	private		::	axis_node(3)	=	c_null_ptr	the axes arrows' switches
type(c_ptr),	private		::	axis_text(3)	=	c_null_ptr	the axes labels (in axis_label_node)
type(FramePointer),	private,	allocatable	::	children(:)			not owned (first n_children, n_parents used)
real(kind=wp),	private		::	color_(4)	=	[1.0_wp, 1.0_wp, 1.0_wp, 0.9_wp]	decorations' color [r, g, b, a] (0 to 1)
logical,	private		::	contents	=	.true.	what the frame draws shown (show_contents)
type(c_ptr),	private		::	contents_node	=	c_null_ptr	switch holding the contents
class(ReferenceFrame),	private,	pointer	::	follow_frame_	=>	null()	the frame the followed data are in (null: the parent)
type(TrajectoryFollower),	private		::	follower_			sets position and attitude from followed trajectories
logical,	private		::	following	=	.false.	following trajectories (follow, until unfollow)
integer,	private		::	label_alignment_	=	ALIGN_LEFT_BASE_LINE	labels' alignment (ALIGN_*)
character(len=:),	private,	allocatable	::	label_font_			labels' font (unallocated: the renderer's default)
integer,	private		::	label_size_	=	20	labels' size (pixels)
real(kind=wp),	private		::	light_ambient_(3)	=	0.05_wp	[r, g, b]
real(kind=wp),	private		::	light_diffuse_(3)	=	0.8_wp	[r, g, b]
type(c_ptr),	private		::	light_node	=	c_null_ptr	light and switch (made when enabled)
logical,	private		::	light_source	=	.false.	carries a light source (set_light_source_enabled)
real(kind=wp),	private		::	light_specular_(3)	=	0.05_wp	[r, g, b]
type(c_ptr),	private		::	light_switch	=	c_null_ptr	light and switch (made when enabled)
integer,	private		::	n_children	=	0	number of children and parents
integer,	private		::	n_parents	=	0	number of children and parents
character(len=:),	private,	allocatable	::	name_			the name (shown by the name label)
logical,	private		::	name_label	=	.true.	the name label shown
type(c_ptr),	private		::	name_label_node	=	c_null_ptr	the name label's switch
logical,	private		::	name_on_top	=	.false.	the name label drawn on top of the scene
type(c_ptr),	private		::	name_text	=	c_null_ptr	the name label (in name_label_node)
type(c_ptr),	private		::	node_	=	c_null_ptr	the frame's transform node
type(FramePointer),	private,	allocatable	::	parents(:)			not owned (first n_children, n_parents used)
logical,	private		::	pickable_	=	.true.	picked (pick); its children aside
real(kind=wp),	private		::	position_(3)	=	0.0_wp	relative to the parent
logical,	private		::	realized	=	.false.	render nodes made (realize)
logical,	private		::	shown_	=	.false.	realized for a window (not headless): later nodes are compiled
integer,	private		::	stamp_	=	0	motion stamp of the last change of its pose or parents
logical,	private		::	synced	=	.false.	the node has synced_position/attitude
real(kind=wp),	private		::	synced_attitude(4)	=	0.0_wp	last copied to the node
real(kind=wp),	private		::	synced_position(3)	=	0.0_wp	last copied to the node
character(len=:),	private,	allocatable	::	x_label_			axes labels (unallocated: 'X', 'Y', 'Z')
character(len=:),	private,	allocatable	::	y_label_			axes labels (unallocated: 'X', 'Y', 'Z')
character(len=:),	private,	allocatable	::	z_label_			axes labels (unallocated: 'X', 'Y', 'Z')

Constructor

The ReferenceFrame constructor: ReferenceFrame(...) makes one (see new_reference_frame for its arguments).

private function new_reference_frame (name, color)	A frame named `name`, with decorations of color `color` ([r, g, b] or [r, g, b, a], 0 to 1; default white, 90% opaque).

Type-Bound Procedures

procedure, public :: add_child
procedure, public :: attitude
procedure, public :: axes_labels_shown
procedure, public :: axes_shown
procedure, public :: axis_label
procedure, public :: bound
procedure, public :: build_contents
procedure, public :: child
procedure, public :: child_index
procedure, public :: color
procedure, public :: contents_shown
procedure, public :: detach
procedure, public :: follow
procedure, public :: follow_frame
procedure, public :: follower
procedure, public :: frame_info
procedure, public :: frame_string
procedure, public :: has_light_source
procedure, public :: is_following
procedure, public :: label_alignment
procedure, public :: label_font
procedure, public :: label_size
procedure, public :: late_update
procedure, public :: light_ambient
procedure, public :: light_diffuse
procedure, public :: light_source_enabled
procedure, public :: light_specular
procedure, public :: local_matrix
procedure, public :: local_matrix_at
procedure, public :: motion_key
procedure, public :: move_x_axis
procedure, public :: move_y_axis
procedure, public :: move_z_axis
procedure, public :: name
procedure, public :: name_label_on_top
procedure, public :: name_label_shown
procedure, public :: node
procedure, public :: num_children
procedure, public :: num_parents
procedure, public :: parent
procedure, public :: parent_index
procedure, public :: pick
procedure, public :: pickable
procedure, public :: position
procedure, public :: position_of
procedure, public :: realize
procedure, public :: remove_child
procedure, public :: reposition_axes
procedure, public :: set_attitude
procedure, public :: set_color
procedure, public :: set_label_alignment
procedure, public :: set_label_font
procedure, public :: set_label_size
procedure, public :: set_light_ambient
procedure, public :: set_light_diffuse
procedure, public :: set_light_source_enabled
procedure, public :: set_light_specular
procedure, public :: set_name
procedure, public :: set_name_label_on_top
procedure, public :: set_pickable
procedure, public :: set_position
procedure, public :: set_x_label
procedure, public :: set_y_label
procedure, public :: set_z_label
procedure, public :: show_axes
procedure, public :: show_axes_labels
procedure, public :: show_contents
procedure, public :: show_decorations
procedure, public :: show_name_label
procedure, public :: sync
procedure, public :: unfollow
procedure, public :: update
procedure, public :: world_matrix
procedure, public :: world_matrix_at

Functions

private function add_child(self, child) result(ok)

Add child to this frame's children. Returns false (and does nothing) for this frame itself or an ancestor of it; true if it is already a child.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout),		target	::	self
class(ReferenceFrame),	intent(inout),		target	::	child	the frame to add (not owned)

Return Value logical

private pure function attitude(self) result(q)

Attitude relative to the parent frame, a quaternion [x, y, z, w].

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value real(kind=wp), (4)

private pure function axes_labels_shown(self)

Which axes labels are shown (as axes_shown).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value integer

private pure function axes_shown(self)

Which axes vectors are shown (NO_AXES, or X_AXIS, Y_AXIS, Z_AXIS combined).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value integer

private function axis_label(self, axis) result(text)

The label text of axis X_AXIS, Y_AXIS or Z_AXIS.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self
integer,	intent(in)			::	axis	X_AXIS, Y_AXIS or Z_AXIS (else: '')

Return Value character(len=:), allocatable

private function child(self, i) result(c)

Child i (1 to num_children).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self
integer,	intent(in)			::	i	1 to num_children

Return Value class(ReferenceFrame), pointer

private function child_index(self, frame)

Index of frame among the children, or 0.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self
class(ReferenceFrame),	intent(in),		target	::	frame	the frame to find

Return Value integer

private pure function color(self) result(c)

The color of the frame's decorations, [r, g, b, a] (0 to 1).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value real(kind=wp), (4)

private pure function contents_shown(self)

Whether what the frame draws is shown (show_contents).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value logical

private function find(list, n, frame)

Index of frame in list(1:n), or 0.

Arguments

Type	Intent	Attributes		Name
type(FramePointer),	intent(in),	allocatable	::	list(:)	first n used
integer,	intent(in)		::	n	number of frames in list
class(ReferenceFrame),	intent(in),	target	::	frame	the frame to find

Return Value integer

private function follow_frame(self) result(f)

The frame the followed data are in (follow's data_frame; null: the parent).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value class(ReferenceFrame), pointer

private function follower(self) result(f)

The frame's trajectory follower, for finer control (data sources, time offset, ...).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in),		target	::	self

Return Value type(TrajectoryFollower), pointer

private function frame_info(self) result(info)

What kind of frame this is (shown by frame_string; extensions override it).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value character(len=:), allocatable

private recursive function frame_string(self, prefix) result(str)

The tree below this frame, one line per frame ("name (info)"), in OpenFrames' createFrameString format: children are prefixed "|-->".

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self
character(len=*),	intent(in),	optional		::	prefix	before this frame's line (default ' ')

Return Value character(len=:), allocatable

private recursive function has_light_source(self) result(has)

Whether this frame or one of its descendants has a light source enabled.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value logical

private recursive function is_descendant(root, frame) result(yes)

True if frame is root or one of its descendants.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in),		target	::	root	the subtree's root; the frame looked for
class(ReferenceFrame),	intent(in),		target	::	frame	the subtree's root; the frame looked for

Return Value logical

private pure function is_following(self)

Whether the frame follows trajectories (at least one, since follow).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value logical

private pure function label_alignment(self)

The labels' alignment (ALIGN_*).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value integer

private function label_font(self) result(font)

The labels' font as set ('' for the renderer's default).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value character(len=:), allocatable

private pure function label_size(self)

The labels' size in pixels.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value integer

private pure function light_ambient(self) result(rgb)

The light source's ambient color [r, g, b].

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value real(kind=wp), (3)

private pure function light_diffuse(self) result(rgb)

The light source's diffuse color [r, g, b].

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value real(kind=wp), (3)

private pure function light_source_enabled(self)

Whether this frame carries a light source.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value logical

private pure function light_specular(self) result(rgb)

The light source's specular color [r, g, b].

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value real(kind=wp), (3)

private pure function local_matrix(self) result(m)

The transform from this frame to its parent (4x4).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value real(kind=wp), (4,4)

private recursive function local_matrix_at(self, t) result(m)

The transform from this frame to its parent at simulation time t: its fixed position and attitude, with what it follows at time t (the followed trajectories' state then, in the parent's coordinates). The same as local_matrix after update at time t, for any t, without changing anything.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self
real(kind=wp),	intent(in)			::	t	simulation time

Return Value real(kind=wp), (4,4)

private function name(self) result(n)

The frame's name ('' if none).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value character(len=:), allocatable

private pure function name_label_on_top(self)

Whether the name label is drawn on top of the scene (set_name_label_on_top).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value logical

private pure function name_label_shown(self)

Whether the name label is shown.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value logical

private function new_reference_frame(name, color) result(frame)

A frame named name, with decorations of color color ([r, g, b] or [r, g, b, a], 0 to 1; default white, 90% opaque).

Arguments

Type	Intent	Optional	Attributes		Name
character(len=*),	intent(in)			::	name	the frame's name (shown by its name label)
real(kind=wp),	intent(in),	optional		::	color(:)	[r, g, b] or [r, g, b, a] (0 to 1; default white, 90% opaque)

Return Value type(ReferenceFrame)

private function node(self) result(n)

The frame's transform node (null until realized).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value type(c_ptr)

private pure function num_children(self)

Number of children.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value integer

private pure function num_parents(self)

Number of parents.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value integer

private function parent(self, i) result(p)

Parent i (1 to num_parents).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self
integer,	intent(in)			::	i	1 to num_parents

Return Value class(ReferenceFrame), pointer

private function parent_index(self, frame)

Index of frame among the parents, or 0.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self
class(ReferenceFrame),	intent(in),		target	::	frame	the frame to find

Return Value integer

public function pick_ellipsoid(self, cam, to_root, center, axes, radii, geodetic, hits, n) result(hit)

Pick a body of frame self: the ellipsoid centered at center with semi-axes radii along the columns of axes (unit vectors; all in the frame's coordinates), hit by the ray through the cursor. Adds a PICK_BODY hit (with the geodetic latitude and longitude of the point on the ellipsoid if geodetic); true if hit.

Arguments

Type	Intent	Attributes		Name
class(ReferenceFrame),	intent(in),	target	::	self
type(PickCamera),	intent(in)		::	cam	the cursor's ray and the pick's settings
real(kind=wp),	intent(in)		::	to_root(4,4)	center, axes: frame coordinates
real(kind=wp),	intent(in)		::	center(3)	center, axes: frame coordinates
real(kind=wp),	intent(in)		::	axes(3,3)	center, axes: frame coordinates
real(kind=wp),	intent(in)		::	radii(3)	center, axes: frame coordinates
logical,	intent(in)		::	geodetic	(true: also the hit's geodetic latitude and longitude)
type(PickHit),	intent(inout),	allocatable	::	hits(:)	hits so far (grown as needed)
integer,	intent(inout)		::	n	number of hits in hits

Return Value logical

private pure function pickable(self)

Whether pick tests what this frame draws (set_pickable).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value logical

private pure function position(self) result(p)

Position relative to the parent frame.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value real(kind=wp), (3)

private function position_of(self, other) result(p)

The origin of other (a frame of the same tree) in this frame's coordinates, from both frames' transforms to the root (through their first parents).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self	(other: a frame of the same tree)
class(ReferenceFrame),	intent(in)			::	other	(other: a frame of the same tree)

Return Value real(kind=wp), (3)

private function remove(list, n, frame)

Remove frame from list(1:n); false if it is not in it.

Arguments

Type	Intent	Attributes		Name
type(FramePointer),	intent(inout),	allocatable	::	list(:)	first n used
integer,	intent(inout)		::	n	number of frames in list (decremented if removed)
class(ReferenceFrame),	intent(in),	target	::	frame	the frame to remove

Return Value logical

private function remove_child(self, child) result(ok)

Remove child from this frame's children. Returns false if it is not one.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout),		target	::	self
class(ReferenceFrame),	intent(inout),		target	::	child	the child to remove

Return Value logical

private function same_frame(a, b)

True if a and b are the same frame (object).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in),		target	::	a	the frames compared
class(ReferenceFrame),	intent(in),		target	::	b	the frames compared

Return Value logical

private recursive function world_matrix(self) result(m)

The transform from this frame to the root of its tree, through the first parent at each level.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self

Return Value real(kind=wp), (4,4)

private recursive function world_matrix_at(self, t) result(m)

The transform from this frame to the root of its tree at simulation time t (through the first parent at each level): each frame's local_matrix_at time t. The same as world_matrix after the tree's update at time t, for any t, without changing anything.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(in)			::	self
real(kind=wp),	intent(in)			::	t	simulation time

Return Value real(kind=wp), (4,4)

Subroutines

public subroutine add_pick_hit(hits, n, hit)

Add hit to hits(1:n) (growing the array).

Arguments

Type	Intent	Attributes		Name
type(PickHit),	intent(inout),	allocatable	::	hits(:)	grown as needed
integer,	intent(inout)		::	n	number of hits in hits
type(PickHit),	intent(in)		::	hit	the hit to add

private subroutine append(list, n, frame)

Add frame to list(1:n) (growing the array).

Arguments

Type	Intent	Attributes		Name
type(FramePointer),	intent(inout),	allocatable	::	list(:)	first n used (grown as needed)
integer,	intent(inout)		::	n	number of frames in list (incremented)
class(ReferenceFrame),	intent(in),	target	::	frame	the frame to add (not owned)

private subroutine apply_light(self)

Give the light source's node its colors (if it has been made).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self

private subroutine bound(self, center, radius)

The bounding sphere of what the frame draws, in its own coordinates (radius 0 if it draws nothing; extensions override it). Views use it for their default distance.

Arguments

Type	Intent		Name
class(ReferenceFrame),	intent(in)	::	self
real(kind=wp),	intent(out)	::	center(3)	frame's coordinates
real(kind=wp),	intent(out)	::	radius	frame's coordinates

private subroutine build_contents(self, viewer, group)

Add what this frame draws to group (a node handle). ReferenceFrame draws nothing itself (its axes and labels come later); extensions such as Sphere and Model override this.

Arguments

Type	Intent		Name
class(ReferenceFrame),	intent(inout)	::	self
type(c_ptr),	intent(in)	::	viewer	(viewer: as realize's)
type(c_ptr),	intent(in)	::	group	(viewer: as realize's)

private subroutine build_decorations(self)

The axes (arrows), axes labels and name label, each under a switch, in the frame's color (OpenFrames' ReferenceFrame decorations).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self

private subroutine build_light(self)

The light source's node: a point light at the origin, under a switch.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self

private subroutine detach(self)

Remove this frame from all its parents and children (before it goes out of scope or is deallocated while in a tree).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout),		target	::	self

private subroutine follow(self, traj, data, mode, add, data_frame)

Follow traj (in addition to trajectories already followed, if add is true), with what to follow (data: FOLLOW_POSITION and/or FOLLOW_ATTITUDE; default both) and how (mode: FOLLOW_LOOP, the default, or FOLLOW_LIMIT). traj must stay alive while followed.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
type(Trajectory),	intent(in),		target	::	traj	the trajectory to follow (not owned)
integer,	intent(in),	optional		::	data	FOLLOW_POSITION/FOLLOW_ATTITUDE; FOLLOW_LOOP/FOLLOW_LIMIT
integer,	intent(in),	optional		::	mode	FOLLOW_POSITION/FOLLOW_ATTITUDE; FOLLOW_LOOP/FOLLOW_LIMIT
logical,	intent(in),	optional		::	add	(true: in addition to those followed (default false))
class(ReferenceFrame),	intent(in),	optional,	target	::	data_frame	the frame the data are in (default: the parent)

private recursive subroutine followed_pose(self, t, pos, att)

The followed position and attitude at time t, in the parent's coordinates (from the data frame's, if follow had one, by both frames' poses at time t); pos and att unchanged where nothing is followed.

Arguments

Type	Intent		Name
class(ReferenceFrame),	intent(in)	::	self
real(kind=wp),	intent(in)	::	t	simulation time
real(kind=wp),	intent(inout)	::	pos(3)	the pose (in the parent's coordinates)
real(kind=wp),	intent(inout)	::	att(4)	the pose (in the parent's coordinates)

private recursive subroutine late_update(self, t)

After the whole tree's update for time t (all frames at their positions for t): for contents that depend on other frames' positions, e.g. CustomLineSegments between spacecraft. Here, only the descendants'.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	t	simulation time

private subroutine make_axis(self, k)

Axis k's arrow and label, in their switches (in place of the old ones; compiled first if the window already runs).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
integer,	intent(in)			::	k	the axis: 1 (x), 2 (y) or 3 (z)

private subroutine make_name_label(self)

The name label (in place of the old one; compiled first if shown).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self

private recursive subroutine motion_key(self, stamp, data)

What the frame's motion depends on, for drawings that depend on it to know when to redraw: stamp, the latest change of the motion of it and its ancestors (through first parents), and of the frames their followed data are in (poses set, parents changed, what is followed and how); and data, the followed trajectories' revisions summed. Either changes when the frame's motion over time changes.

Arguments

Type	Intent		Name
class(ReferenceFrame),	intent(in)	::	self
integer,	intent(out)	::	stamp	the latest change; the followed data's revisions
integer,	intent(out)	::	data	the latest change; the followed data's revisions

private subroutine move_axis(self, k, base, length, head_ratio, body_radius, head_radius)

Place axis k (as move_x_axis), made again if the frame is shown.

Arguments

Type	Intent	Optional		Name
class(ReferenceFrame),	intent(inout)		::	self
integer,	intent(in)		::	k	the axis: 1 (x), 2 (y) or 3 (z)
real(kind=wp),	intent(in)		::	base(3)	(base: frame's coordinates)
real(kind=wp),	intent(in)		::	length	(base: frame's coordinates)
real(kind=wp),	intent(in),	optional	::	head_ratio	defaults: 0.3; 0.05 and 0.1 of the length
real(kind=wp),	intent(in),	optional	::	body_radius	defaults: 0.3; 0.05 and 0.1 of the length
real(kind=wp),	intent(in),	optional	::	head_radius	defaults: 0.3; 0.05 and 0.1 of the length

private subroutine move_x_axis(self, base, length, head_ratio, body_radius, head_radius)

Place the x axis vector: from base, length long, with a head of head_ratio of the length (default 0.3) and body and head radii (default 0.05 and 0.1 of the length); its label is at the tip, 0.4 of the length tall (at most label_size pixels). As OpenFrames' moveXAxis. Set before the frame is first shown.

Arguments

Type	Intent	Optional		Name
class(ReferenceFrame),	intent(inout)		::	self
real(kind=wp),	intent(in)		::	base(3)	(base: frame's coordinates)
real(kind=wp),	intent(in)		::	length	(base: frame's coordinates)
real(kind=wp),	intent(in),	optional	::	head_ratio	defaults: 0.3; 0.05 and 0.1 of the length
real(kind=wp),	intent(in),	optional	::	body_radius	defaults: 0.3; 0.05 and 0.1 of the length
real(kind=wp),	intent(in),	optional	::	head_radius	defaults: 0.3; 0.05 and 0.1 of the length

private subroutine move_y_axis(self, base, length, head_ratio, body_radius, head_radius)

Place the y axis vector (as move_x_axis; OpenFrames' moveYAxis).

Arguments

Type	Intent	Optional		Name
class(ReferenceFrame),	intent(inout)		::	self
real(kind=wp),	intent(in)		::	base(3)	(base: frame's coordinates)
real(kind=wp),	intent(in)		::	length	(base: frame's coordinates)
real(kind=wp),	intent(in),	optional	::	head_ratio	defaults: 0.3; 0.05 and 0.1 of the length
real(kind=wp),	intent(in),	optional	::	body_radius	defaults: 0.3; 0.05 and 0.1 of the length
real(kind=wp),	intent(in),	optional	::	head_radius	defaults: 0.3; 0.05 and 0.1 of the length

private subroutine move_z_axis(self, base, length, head_ratio, body_radius, head_radius)

Place the z axis vector (as move_x_axis; OpenFrames' moveZAxis).

Arguments

Type	Intent	Optional		Name
class(ReferenceFrame),	intent(inout)		::	self
real(kind=wp),	intent(in)		::	base(3)	(base: frame's coordinates)
real(kind=wp),	intent(in)		::	length	(base: frame's coordinates)
real(kind=wp),	intent(in),	optional	::	head_ratio	defaults: 0.3; 0.05 and 0.1 of the length
real(kind=wp),	intent(in),	optional	::	body_radius	defaults: 0.3; 0.05 and 0.1 of the length
real(kind=wp),	intent(in),	optional	::	head_radius	defaults: 0.3; 0.05 and 0.1 of the length

private subroutine pick(self, cam, to_root, hits, n)

Pick what the frame draws (see the module documentation): to_root is its transform to the root frame; hits are added to hits(1:n). A plain frame: its origin, if it shows axes or its name label.

Arguments

Type	Intent	Attributes		Name
class(ReferenceFrame),	intent(in),	target	::	self
type(PickCamera),	intent(in)		::	cam	the cursor's ray and the pick's settings
real(kind=wp),	intent(in)		::	to_root(4,4)	the frame's transform to the root frame
type(PickHit),	intent(inout),	allocatable	::	hits(:)	hits so far (grown as needed)
integer,	intent(inout)		::	n	number of hits in hits

private recursive subroutine realize(self, viewer)

Create the render nodes of this frame and its descendants (once; for viewer, a window's viewer handle, which some contents need while they are built (not kept); null: headless).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
type(c_ptr),	intent(in)			::	viewer	a window's viewer handle (null: headless)

private subroutine relayout_labels(self)

The labels' size and alignment changed: the name label's in place, the axes' labels made again.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self

private subroutine remake_axes(self)

The axes and their labels made again (another color, size or font).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self

private subroutine replace_child(self, switch, old, new)

Put new in switch in place of old (a kept handle, deleted).

Arguments

Type	Intent		Name
class(ReferenceFrame),	intent(in)	::	self
type(c_ptr),	intent(in)	::	switch	the switch; the new node (may be null)
type(c_ptr),	intent(inout)	::	old	the node replaced (deleted; set to new)
type(c_ptr),	intent(in)	::	new	the switch; the new node (may be null)

private subroutine reposition_axes(self)

Place the axes for what the frame draws, when it is first shown (unless move_*_axis was called): at its bound's surface, half the bound's radius long (as OpenFrames' Sphere and Model do); at the origin, 1 long, for a frame that draws nothing.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self

private subroutine set_attitude(self, q)

Attitude relative to the parent frame, a quaternion [x, y, z, w] (normalized here; overridden by a followed trajectory).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	q(4)	attitude quaternion [x, y, z, w] (normalized here)

private subroutine set_color(self, color)

The color of the frame's decorations: [r, g, b] (alpha unchanged) or [r, g, b, a].

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	color(:)	[r, g, b] (alpha unchanged) or [r, g, b, a] (0 to 1)

private subroutine set_label_alignment(self, alignment)

The alignment of the labels relative to their positions (ALIGN_*; default ALIGN_LEFT_BASE_LINE).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
integer,	intent(in)			::	alignment	ALIGN_* (default ALIGN_LEFT_BASE_LINE)

private subroutine set_label_font(self, font)

The font of the labels: a font file name (found on the data search path) or a full path; default: the renderer's default font.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
character(len=*),	intent(in)			::	font	a font file name (on the data search path) or a full path

private subroutine set_label_size(self, size)

The size of the labels in pixels (default 20): the name label's size, and the maximum size of the axes labels (which shrink with distance).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
integer,	intent(in)			::	size	pixels (default 20)

private subroutine set_light_ambient(self, rgb)

The light source's ambient, diffuse and specular colors ([r, g, b], 0 to 1; defaults 0.05, 0.8 and 0.05 gray).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	rgb(3)	ambient color [r, g, b] (0 to 1; default 0.05 gray)

private subroutine set_light_diffuse(self, rgb)

The light source's diffuse color (see set_light_ambient).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	rgb(3)	diffuse color [r, g, b] (0 to 1; default 0.8 gray)

private subroutine set_light_source_enabled(self, enable)

Whether this frame carries a light source: a point light at its origin (e.g. the Sun), not dimmed with distance (default false; OpenFrames' setLightSourceEnabled). While any frame of a window's scene has one, the window's own light (WindowProxy%set_light_*) is off.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
logical,	intent(in)			::	enable	(true: a point light at the frame's origin)

private subroutine set_light_specular(self, rgb)

The light source's specular color (see set_light_ambient).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	rgb(3)	specular color [r, g, b] (0 to 1; default 0.05 gray)

private subroutine set_name(self, name)

The frame's name, shown by its name label (also once shown: e.g. a readout that follows the frame).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
character(len=*),	intent(in)			::	name	the name (shown by the name label)

private subroutine set_name_label_on_top(self, on_top)

Draw the name label on top of the scene (true: not hidden by bodies in front of it, as HUD text; e.g. a readout) or depth-tested (false, the default, as OpenFrames').

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
logical,	intent(in)			::	on_top	(true: drawn on top of the scene; false: depth-tested)

private subroutine set_pickable(self, pickable)

Whether pick tests what this frame draws (default true; e.g. false for an overlay such as a selection marker). Its children are picked or not by their own setting.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
logical,	intent(in)			::	pickable	(true: tested by pick)

private subroutine set_position(self, position)

Position relative to the parent frame (overridden by a followed trajectory).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	position(3)	parent frame's coordinates

private subroutine set_x_label(self, text)

The text of the x-axis label (default 'X').

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
character(len=*),	intent(in)			::	text	the x-axis label (default 'X')

private subroutine set_y_label(self, text)

The text of the y-axis label (default 'Y').

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
character(len=*),	intent(in)			::	text	the y-axis label (default 'Y')

private subroutine set_z_label(self, text)

The text of the z-axis label (default 'Z').

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
character(len=*),	intent(in)			::	text	the z-axis label (default 'Z')

private subroutine show_axes(self, axes)

Which axes vectors to show: NO_AXES, or X_AXIS, Y_AXIS, Z_AXIS combined with ior.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
integer,	intent(in)			::	axes	NO_AXES, or X_AXIS, Y_AXIS, Z_AXIS combined with ior

private subroutine show_axes_labels(self, labels)

Which axes labels to show (as show_axes).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
integer,	intent(in)			::	labels	NO_AXES, or X_AXIS, Y_AXIS, Z_AXIS combined with ior

private subroutine show_contents(self, show)

Show or hide what the frame draws (its sphere, model, ...), but not its axes, labels or children.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
logical,	intent(in)			::	show	(true: shown)

private subroutine show_decorations(self, show)

Show (true) or hide all the frame's decorations at once: its axes, their labels and its name label (show_axes, show_axes_labels, show_name_label).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
logical,	intent(in)			::	show	true: all axes, axes labels and the name label

private subroutine show_name_label(self, show)

Show or hide the name label (at the frame's origin; default shown).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self
logical,	intent(in)			::	show	(true: shown)

private recursive subroutine sync(self)

Copy the positions and attitudes of this frame and its descendants to their transform nodes (only those that changed since the last sync).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self

private subroutine unfollow(self)

Stop following trajectories (the frame keeps its last position and attitude).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self

private recursive subroutine update(self, t)

Update this frame and its descendants for simulation time t (followed trajectories set positions and attitudes).

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout),		target	::	self
real(kind=wp),	intent(in)			::	t	simulation time

private subroutine update_switches(self)

Show or hide the decorations' switches as set.

Arguments

Type	Intent	Optional	Attributes		Name
class(ReferenceFrame),	intent(inout)			::	self

vkf_frames Module

Contents

Variables

Interfaces

Derived Types

Functions

Subroutines

Uses

Used by

Variables

Interfaces

public interface ReferenceFrame

private function new_reference_frame(name, color) result(frame)

Arguments

Return Value type(ReferenceFrame)

Derived Types

type, public :: FramePointer

Components

type, public :: PickHit

Components

type, public :: ReferenceFrame

Components

Constructor

Type-Bound Procedures

Functions

private function add_child(self, child) result(ok)

Arguments

Return Value logical

private pure function attitude(self) result(q)

Arguments

Return Value real(kind=wp), (4)

private pure function axes_labels_shown(self)

Arguments

Return Value integer

private pure function axes_shown(self)

Arguments

Return Value integer

private function axis_label(self, axis) result(text)

Arguments

Return Value character(len=:), allocatable

private function child(self, i) result(c)

Arguments

Return Value class(ReferenceFrame), pointer

private function child_index(self, frame)

Arguments

Return Value integer

private pure function color(self) result(c)

Arguments

Return Value real(kind=wp), (4)

private pure function contents_shown(self)

Arguments

Return Value logical

private function find(list, n, frame)

Arguments

Return Value integer

private function follow_frame(self) result(f)

Arguments

Return Value class(ReferenceFrame), pointer

private function follower(self) result(f)

Arguments

Return Value type(TrajectoryFollower), pointer

private function frame_info(self) result(info)

Arguments

Return Value character(len=:), allocatable

private recursive function frame_string(self, prefix) result(str)

Arguments

Return Value character(len=:), allocatable

private recursive function has_light_source(self) result(has)

Arguments

Return Value logical

private recursive function is_descendant(root, frame) result(yes)

Arguments

Return Value logical

private pure function is_following(self)

Arguments

Return Value logical

private pure function label_alignment(self)

Arguments

Return Value integer

private function label_font(self) result(font)