vkf_sky – vkframes

The sky behind a scene (OpenFrames' SkySphere): a texture map and/or stars from a star catalog, at infinity (they turn with the view, never move with it), in the root frame's axes turned by the sky's attitude. A window shows a sky with set_sky; one sky can be shown in several windows.

Texture: an equirectangular image of the sky (right ascension across, declination down; as a Sphere's texture map), e.g. OpenFrames' Images/StarMap.tif.
Stars: a star catalog in OpenFrames' text format (e.g. the HYG v3 catalog of OpenFrames, data/Stars_HYGv3.txt): a header line "ra[_limit] dec mag ci proper", then a star per line: right ascension (in hours, or 0 to limit if the header says "ra_limit", e.g. "ra_360.0"), declination (degrees), apparent magnitude, optional B-V color index and name. Stars in a magnitude range are drawn (at most a number of them, in catalog order), sized from their brightness between a minimum and a maximum size (window units), colored from their color index, and the smaller dimmed (OpenFrames' SkySphere::processStars and StarToPoint).
Star names: the names of the catalog's named stars drawn (those of them up to a magnitude), as labels beside them, at infinity as the stars (behind the scene); off by default (set_star_names). Shown with the stars (draw mode SKY_STARS).
Constellations: faint lines between their stars, from a constellation file (e.g. data/inp_Constellation.txt, Chris Dolan's outlines): "N name" starts a constellation, then a line per segment, "dec1 ra1 dec2 ra2" (degrees, hours), then an optional "# comment"; lines starting with "#" are comments. Off by default (set_constellations); at infinity, behind the stars, shown unless the draw mode is SKY_NONE.

Both are drawn when given (draw mode SKY_TEXTURE + SKY_STARS); the stars over the texture, by the brighter color.

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,	private,	parameter	::	NAME_ALIGNMENT	=	1	star names' alignment: vkf_frames' ALIGN_LEFT_CENTER
integer,	public,	parameter	::	SKY_NONE	=	0	What a sky draws (OpenFrames' SkySphere::DrawMode; add them).
integer,	public,	parameter	::	SKY_STARS	=	2	What a sky draws (OpenFrames' SkySphere::DrawMode; add them).
integer,	public,	parameter	::	SKY_TEXTURE	=	1	What a sky draws (OpenFrames' SkySphere::DrawMode; add them).
character(len=*),	public,	parameter	::	default_constellations	=	'inp_Constellation.txt'	The constellation file read when none is given: vkframes' (data/).

Derived Types

type, private :: Constellation

A constellation of those read: its name and its lines (columns of self%lines).

Components

Type	Visibility	Attributes		Name		Initial
integer,	public		::	first	=	1	its lines: first .. last
integer,	public		::	last	=	0	its lines: first .. last
character(len=:),	public,	allocatable	::	name			the file's name for it

type, public :: SkySphere

The sky behind a scene (OpenFrames' SkySphere; see the module documentation).

Components

Type	Visibility	Attributes		Name		Initial
real(kind=wp),	private		::	attitude_(4)	=	[0.0_wp, 0.0_wp, 0.0_wp, 1.0_wp]	in the root frame (quaternion [x, y, z, w])
character(len=:),	private,	allocatable	::	catalog			star catalog file (unallocated or '': none)
character(len=:),	private,	allocatable	::	constellation_file			the file read (unallocated: none yet)
type(Constellation),	private,	allocatable	::	groups(:)			the constellations read (n_groups of them)
type(c_ptr),	private		::	image	=	c_null_ptr	the texture image (null: none)
type(c_ptr),	private		::	line_node	=	c_null_ptr	the constellations drawing (null: none)
type(c_ptr),	private		::	line_switch	=	c_null_ptr	shows or hides the constellations (draw mode)
real(kind=c_float),	private,	allocatable	::	lines(:,:)			(8, n): the lines' ends, directions (x, y, z, -)
real(kind=wp),	private		::	lines_rgba(4)	=	[0.35_wp, 0.5_wp, 0.8_wp, 0.45_wp]	their color (faint)
logical,	private		::	lines_shown	=	.false.	the constellations are drawn
real(kind=wp),	private		::	lines_width	=	1.0_wp	window units
real(kind=wp),	private		::	mag_range(2)	=	0.0_wp	of the stars read
real(kind=wp),	private		::	max_mag	=	8.0_wp	OpenFrames' SkySphere defaults
real(kind=wp),	private		::	max_size	=	10.0_wp	window units
integer,	private		::	max_stars	=	10000	the most stars drawn
real(kind=wp),	private		::	min_dim	=	0.5_wp	the smallest stars' color scale (0 to 1)
real(kind=wp),	private		::	min_mag	=	-2.0_wp	OpenFrames' SkySphere defaults
real(kind=wp),	private		::	min_size	=	1.0_wp	window units
integer,	private		::	mode	=	SKY_TEXTURE+SKY_STARS	SKY_NONE, or a sum of SKY_TEXTURE and SKY_STARS
integer,	private		::	n_groups	=	0	constellations read
integer,	private		::	n_labels	=	0	names drawn
integer,	private		::	n_lines	=	0	lines read: columns of lines used
integer,	private		::	n_names	=	0	named stars read
integer,	private		::	n_stars	=	0	stars read: columns of stars used
type(c_ptr),	private		::	name_node	=	c_null_ptr	the star names, a transform: the attitude (null: none)
type(StarName),	private,	allocatable	::	names(:)			the named stars read (n_names of them)
character(len=:),	private,	allocatable	::	names_font			font ('' or unallocated: the default)
real(kind=wp),	private		::	names_max_mag	=	huge(1.0_wp)	names of stars up to this magnitude
real(kind=wp),	private		::	names_rgba(4)	=	[0.6_wp, 0.7_wp, 0.9_wp, 1.0_wp]	color
logical,	private		::	names_shown	=	.false.	the names are drawn
real(kind=wp),	private		::	names_size	=	12.0_wp	window units
type(c_ptr),	private		::	root	=	c_null_ptr	the sky's node, a transform (null until made)
logical,	private		::	shown	=	.false.	made for a window: nodes made later are compiled
type(c_ptr),	private		::	star_node	=	c_null_ptr	the stars drawing (null: none)
type(c_ptr),	private		::	star_switch	=	c_null_ptr	shows or hides the stars (draw mode)
real(kind=c_float),	private,	allocatable	::	stars(:,:)			(8, n): direction, size, rgb, -
character(len=:),	private,	allocatable	::	texture_file			texture image file (unallocated or '': none)
type(c_ptr),	private		::	texture_node	=	c_null_ptr	the texture drawing (null: none)
type(c_ptr),	private		::	texture_switch	=	c_null_ptr	shows or hides the texture (draw mode)

Type-Bound Procedures

procedure, public :: attitude
procedure, public :: constellation_file_read
procedure, public :: constellation_line
procedure, public :: constellation_lines
procedure, public :: constellation_name
procedure, public :: constellations
procedure, public :: draw_mode
procedure, public :: node
procedure, public :: num_constellation_lines
procedure, public :: num_constellations
procedure, public :: num_star_names
procedure, public :: num_star_names_drawn
procedure, public :: num_stars
procedure, public :: set_attitude
procedure, public :: set_constellations
procedure, public :: set_draw_mode
procedure, public :: set_star_data
procedure, public :: set_star_names
procedure, public :: set_texture_map
procedure, public :: star
procedure, public :: star_catalog
procedure, public :: star_magnitude_range
procedure, public :: star_magnitudes
procedure, public :: star_name
procedure, public :: star_names
procedure, public :: star_sizes
procedure, public :: texture_map

type, private :: StarName

A named star of those read: its name and magnitude, its direction in the stars read (self%stars).

Components

Type	Visibility	Attributes		Name		Initial
real(kind=wp),	public		::	mag	=	0.0_wp	apparent magnitude
integer,	public		::	star	=	0	the star's column in self%stars
character(len=:),	public,	allocatable	::	text			the catalog's name

Functions

private pure function after_fields(line, n) result(rest)

The text of line after its first n fields (separated by blanks or tabs), trimmed: a star's name ('' if none: e.g. without a color index).

Arguments

Type	Intent	Optional	Attributes		Name
character(len=*),	intent(in)			::	line	a line of the star catalog
integer,	intent(in)			::	n	fields skipped

Return Value character(len=:), allocatable

private pure function attitude(self) result(q)

The sky's attitude in the root frame (quaternion [x, y, z, w]).

Arguments

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

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

private function constellation_file_read(self) result(file)

The constellation file read ('' for none).

Arguments

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

Return Value character(len=:), allocatable

private function constellation_name(self, i) result(name)

Constellation i's name (1 to num_constellations).

Arguments

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

Return Value character(len=:), allocatable

private pure function constellations(self)

Whether the constellations are drawn (as set).

Arguments

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

Return Value logical

private pure function draw_mode(self)

What is drawn: SKY_NONE, or a sum of SKY_TEXTURE and SKY_STARS.

Arguments

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

Return Value integer

private function node(self, viewer) result(n)

The sky's node, made on first use, for a window (set_sky). For a window's viewer (null: headless), nodes made later (a new texture or catalog) are compiled for the windows running.

Arguments

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

Return Value type(c_ptr)

private pure function num_constellation_lines(self)

Number of constellation lines read (of all of them).

Arguments

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

Return Value integer

private pure function num_constellations(self)

Number of constellations read.

Arguments

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

Return Value integer

private pure function num_star_names(self)

Number of named stars read (of the stars read).

Arguments

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

Return Value integer

private pure function num_star_names_drawn(self)

Number of star names drawn now (0 until the sky is shown, or if the names aren't).

Arguments

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

Return Value integer

private pure function num_stars(self)

Number of stars read.

Arguments

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

Return Value integer

private pure function raw_size(mag)

A star's pixel diameter from its apparent magnitude, from its brightness and luminance (OpenFrames' getStarPixelSizeFromMagnitude).

Arguments

Type	Intent	Optional	Attributes		Name
real(kind=wp),	intent(in)			::	mag	apparent magnitude

Return Value real(kind=wp)

private function read_constellations(self, file) result(ok)

Read the constellations of file (found with find_data_file; '' for none) into self%lines and self%groups, in place of those read before. False (those kept) if it can't be found or read.

Arguments

Type	Intent	Optional	Attributes		Name
type(SkySphere),	intent(inout)			::	self
character(len=*),	intent(in)			::	file	constellation file ('' for none)

Return Value logical

private function read_stars(self) result(ok)

Read the stars of the catalog into self%stars.

Arguments

Type	Intent	Optional	Attributes		Name
type(SkySphere),	intent(inout)			::	self

Return Value logical

private function set_constellations(self, shown, file, rgba, width) result(ok)

Draw the constellations: faint lines between their stars, from constellation file file (found with find_data_file; read when given, or when first shown without one: default_constellations), shown (default false), in color rgba (default a faint blue, alpha 0.45) and width window units wide (default 1). Also while shown; the settings not given are kept. Returns false if the file can't be read (the constellations read before are kept) or width isn't > 0 (nothing changed).

Arguments

Type	Intent	Optional		Name
class(SkySphere),	intent(inout)		::	self
logical,	intent(in)		::	shown	draw the constellations
character(len=*),	intent(in),	optional	::	file	constellation file
real(kind=wp),	intent(in),	optional	::	rgba(4)	color [r, g, b, a] (0 to 1)
real(kind=wp),	intent(in),	optional	::	width	window units (> 0)

Return Value logical

private function set_star_data(self, catalog, min_mag, max_mag, max_stars, min_size, max_size, min_dim_ratio) result(ok)

Draw the stars of catalog (found with find_data_file; '' for none) with magnitudes from min_mag to max_mag (default -2 to 8), at most max_stars (default 10000), sized from min_size to max_size window units (default 1 to 10) by brightness, the smallest dimmed to min_dim_ratio (0 to 1, default 0.5) of their color (OpenFrames' setSkySphereStarData). Returns false if the catalog cannot be read or the limits are invalid (min_mag > max_mag, max_stars < 1, min_size > max_size, a ratio outside 0 to 1).

Arguments

Type	Intent	Optional		Name
class(SkySphere),	intent(inout)		::	self
character(len=*),	intent(in)		::	catalog	star catalog file; '' for none
real(kind=wp),	intent(in),	optional	::	min_mag	apparent magnitudes
real(kind=wp),	intent(in),	optional	::	max_mag	apparent magnitudes
integer,	intent(in),	optional	::	max_stars	the most stars drawn (default 10000; >= 1)
real(kind=wp),	intent(in),	optional	::	min_size	window units
real(kind=wp),	intent(in),	optional	::	max_size	window units
real(kind=wp),	intent(in),	optional	::	min_dim_ratio	0 to 1

Return Value logical

private function set_star_names(self, shown, max_mag, size, rgba, font) result(ok)

Draw the names of the named stars drawn (those of the catalog's last field), beside them: shown (default false), of the stars up to magnitude max_mag (default all of them), size window units tall (default 12), in color rgba (default a pale blue) and font font ('' or default: vkframes' default font). Also while shown; the settings not given are kept. Returns false (nothing changed) if size isn't > 0.

Arguments

Type	Intent	Optional		Name
class(SkySphere),	intent(inout)		::	self
logical,	intent(in)		::	shown	draw the names
real(kind=wp),	intent(in),	optional	::	max_mag	the dimmest named (apparent magnitude)
real(kind=wp),	intent(in),	optional	::	size	height in window units (> 0)
real(kind=wp),	intent(in),	optional	::	rgba(4)	color [r, g, b, a] (0 to 1)
character(len=*),	intent(in),	optional	::	font	font file ('' for the default)

Return Value logical

private function set_texture_map(self, file) result(ok)

Draw an image file as the sky (found with find_data_file); '' for none. Returns false if it cannot be read (the sky is then unchanged).

Arguments

Type	Intent	Optional	Attributes		Name
class(SkySphere),	intent(inout)			::	self
character(len=*),	intent(in)			::	file	image file; '' for none

Return Value logical

private pure function size_of(a)

The number of columns of a (the stars' capacity).

Arguments

Type	Intent	Optional	Attributes		Name
real(kind=c_float),	intent(in)			::	a(:,:)	(8, capacity): the stars array

Return Value integer

private pure function sky_direction(ra, dec) result(dir)

The unit vector of a direction on the sky from its right ascension (hours) and declination (degrees), as the stars' (star_to_point).

Arguments

Type	Intent	Optional	Attributes		Name
real(kind=wp),	intent(in)			::	ra	right ascension (hours)
real(kind=wp),	intent(in)			::	dec	declination (degrees)

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

private function star_catalog(self) result(file)

The star catalog file ('' for none).

Arguments

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

Return Value character(len=:), allocatable

private pure function star_magnitude_range(self) result(m)

The range of magnitudes of the stars read.

Arguments

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

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

private pure function star_magnitudes(self) result(m)

The magnitude range drawn (as set).

Arguments

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

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

private pure function star_names(self)

Whether the star names are drawn (as set).

Arguments

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

Return Value logical

private pure function star_sizes(self) result(s)

The size range of the stars (window units).

Arguments

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

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

private function texture_map(self) result(file)

The texture file ('' for none).

Arguments

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

Return Value character(len=:), allocatable

Subroutines

private subroutine add_name(self, name, mag)

Remember the name of the star just read (self%n_stars), if it has one.

Arguments

Type	Intent		Name
type(SkySphere),	intent(inout)	::	self
character(len=*),	intent(in)	::	name	its name ('' for none)
real(kind=wp),	intent(in)	::	mag	its apparent magnitude

private subroutine apply_attitude(self, n)

The attitude matrix (column-major 4x4) into a sky node's style.

Arguments

Type	Intent	Optional	Attributes		Name
type(SkySphere),	intent(in)			::	self
type(c_ptr),	intent(in)			::	n	a sky node, texture or stars (null: nothing done)

private subroutine apply_mode(self)

Show or hide the texture, the constellations and the stars (and their names), as the draw mode says.

Arguments

Type	Intent	Optional	Attributes		Name
type(SkySphere),	intent(in)			::	self

private subroutine apply_name_attitude(self)

The sky's attitude into the star names' transform.

Arguments

Type	Intent	Optional	Attributes		Name
type(SkySphere),	intent(in)			::	self

private pure subroutine constellation_line(self, i, a, b)

Constellation line i (1 to num_constellation_lines): its ends' directions (unit vectors, sky frame).

Arguments

Type	Intent		Name
class(SkySphere),	intent(in)	::	self
integer,	intent(in)	::	i	1 to num_constellation_lines
real(kind=wp),	intent(out)	::	a(3)	unit vectors, sky frame
real(kind=wp),	intent(out)	::	b(3)	unit vectors, sky frame

private pure subroutine constellation_lines(self, i, first, last)

Constellation i's lines (1 to num_constellations): first .. last (see constellation_line; none if last < first).

Arguments

Type	Intent		Name
class(SkySphere),	intent(in)	::	self
integer,	intent(in)	::	i	1 to num_constellations
integer,	intent(out)	::	first	its lines
integer,	intent(out)	::	last	its lines

private subroutine make_line_node(self)

The constellations node for the lines read and the settings, in place of the old one (none unless shown).

Arguments

Type	Intent	Optional	Attributes		Name
type(SkySphere),	intent(inout)			::	self

private subroutine make_name_node(self)

The star names node for the current names and settings, in place of the old one: a label per named star drawn up to the names' magnitude, under the stars' switch (shown with them), turned by the sky's attitude.

Arguments

Type	Intent	Optional	Attributes		Name
type(SkySphere),	intent(inout)			::	self

private subroutine make_star_node(self)

The star node for the current stars, in place of the old one.

Arguments

Type	Intent	Optional	Attributes		Name
type(SkySphere),	intent(inout)			::	self

private subroutine make_texture_node(self)

The texture node for the current image, in place of the old one.

Arguments

Type	Intent	Optional	Attributes		Name
type(SkySphere),	intent(inout)			::	self

private subroutine set_attitude(self, q)

The sky's attitude in the root frame (quaternion [x, y, z, w]): e.g. to turn an equatorial catalog into an ecliptic root frame.

Arguments

Type	Intent	Optional	Attributes		Name
class(SkySphere),	intent(inout)			::	self
real(kind=wp),	intent(in)			::	q(4)	quaternion [x, y, z, w] (any length > 0)

private subroutine set_draw_mode(self, mode)

What to draw: SKY_NONE, or SKY_TEXTURE + SKY_STARS (default; each only if given).

Arguments

Type	Intent	Optional	Attributes		Name
class(SkySphere),	intent(inout)			::	self
integer,	intent(in)			::	mode	SKY_NONE, or a sum of SKY_TEXTURE and SKY_STARS

private pure subroutine star(self, i, direction, rgb, size)

Star i (1 to num_stars): its direction (unit vector, sky frame), color (rgb, dimmed) and size (window units).

Arguments

Type	Intent		Name
class(SkySphere),	intent(in)	::	self
integer,	intent(in)	::	i	1 to num_stars
real(kind=wp),	intent(out)	::	direction(3)	unit vector, sky frame
real(kind=wp),	intent(out)	::	rgb(3)	color, dimmed (0 to 1)
real(kind=wp),	intent(out)	::	size	window units

private subroutine star_name(self, i, name, mag, which)

Named star i (1 to num_star_names): its name, apparent magnitude and star (1 to num_stars: see star).

Arguments

Type	Intent	Attributes		Name
class(SkySphere),	intent(in)		::	self
integer,	intent(in)		::	i	1 to num_star_names
character(len=:),	intent(out),	allocatable	::	name	the catalog's name
real(kind=wp),	intent(out)		::	mag	apparent magnitude
integer,	intent(out)		::	which	the star (1 to num_stars)

private pure subroutine star_to_point(ra, dec, mag, ci, dir, rgb, size)

A star's direction, color (from its B-V color index: Ballesteros' temperature, then Tanner Helland's temperature to RGB) and raw size (OpenFrames' SkySphere::StarToPoint).

Arguments

Type	Intent		Name
real(kind=wp),	intent(in)	::	ra	right ascension and declination (radians)
real(kind=wp),	intent(in)	::	dec	right ascension and declination (radians)
real(kind=wp),	intent(in)	::	mag	apparent magnitude and B-V color index
real(kind=wp),	intent(in)	::	ci	apparent magnitude and B-V color index
real(kind=wp),	intent(out)	::	dir(3)	unit vector
real(kind=wp),	intent(out)	::	rgb(3)	color (0 to 1)
real(kind=wp),	intent(out)	::	size	raw size (as raw_size)

vkf_sky Module

Contents

Variables

Derived Types

Functions

Subroutines

Uses

Used by

Variables

Derived Types

type, private :: Constellation

Components

type, public :: SkySphere

Components

Type-Bound Procedures

type, private :: StarName

Components

Functions

private pure function after_fields(line, n) result(rest)

Arguments

Return Value character(len=:), allocatable

private pure function attitude(self) result(q)

Arguments

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

private function constellation_file_read(self) result(file)

Arguments

Return Value character(len=:), allocatable

private function constellation_name(self, i) result(name)

Arguments

Return Value character(len=:), allocatable

private pure function constellations(self)

Arguments

Return Value logical

private pure function draw_mode(self)

Arguments

Return Value integer

private function node(self, viewer) result(n)

Arguments

Return Value type(c_ptr)

private pure function num_constellation_lines(self)

Arguments

Return Value integer

private pure function num_constellations(self)

Arguments

Return Value integer

private pure function num_star_names(self)

Arguments

Return Value integer

private pure function num_star_names_drawn(self)

Arguments

Return Value integer

private pure function num_stars(self)

Arguments

Return Value integer

private pure function raw_size(mag)

Arguments

Return Value real(kind=wp)

private function read_constellations(self, file) result(ok)

Arguments

Return Value logical

private function read_stars(self) result(ok)

Arguments

Return Value logical

private function set_constellations(self, shown, file, rgba, width) result(ok)

Arguments

Return Value logical

private function set_star_data(self, catalog, min_mag, max_mag, max_stars, min_size, max_size, min_dim_ratio) result(ok)

Arguments

Return Value logical

private function set_star_names(self, shown, max_mag, size, rgba, font) result(ok)

Arguments

Return Value logical

private function set_texture_map(self, file) result(ok)

Arguments

Return Value logical

private pure function size_of(a)

Arguments

Return Value integer

private pure function sky_direction(ra, dec) result(dir)

Arguments