ImageSet

class wwt_data_formats.imageset.ImageSet(**kwargs: Any)

Bases: LockedXmlTraits, UrlContainer

A WWT imagery dataset.

Instances of this class express WWT imagery datasets and their spatial positioning. Imagesets are exposed to the WWT engine through their XML serialization in a WTML Folder. The engine can be instructed to load such a folder, making its imagesets available for rendering.

Attributes Summary

alt_url	An alternative URL that provided the data.
band_pass	The bandpass of the image data.
base_degrees_per_tile	The angular scale of the image.
base_tile_level	The level of the highest (coarsest-resolution) tiling available.
bottoms_up	The parity of the image's projection on the sky.
center_x	The horizontal location of the center of the image’s projection coordinate system.
center_y	The vertical location of the center of the image’s projection coordinate system.
credits	Textual credits for the image originator.
credits_url	A URL giving the source of the image or more information about its creation.
cross_validation_lock	A contextmanager for running a block with our cross validation lock set to True.
data_max	Highest data value of a FITS file.
data_min	Lowest data value of a FITS file.
data_set_type	The renderer mode to which these data apply.
dem_url	The URL of the DEM data.
description	A textual description of the imagery.
elevation_model	TBD.
file_type	The extension(s) of the image file(s) in this set.
generic	TBD.
mean_radius	TBD.
msr_community_id	The ID number of the WWT Community that this content came from.
msr_component_id	The ID number of this content item on the WWT Communities system.
name	A name used to refer to this imageset.
offset_x	The horizontal positioning of the image relative to its projection coordinate system.
offset_y	The vertical positioning of the image relative to its projection coordinate system.
permission	TBD.
pixel_cut_high	Suggested default high cutoff value when displaying FITS.
pixel_cut_low	Suggested default low cutoff value when displaying FITS.
projection	The type of projection used to place this image on the sky.
quad_tree_map	TBD.
reference_frame	TBD.
rmeta	Runtime metadata - a namespace object for attaching arbitrary extra information
rotation_deg	The rotation of image’s projection coordinate system, in degrees.
sparse	TBD.
stock_set	TBD.
thumbnail_url	A URL to a standard WWT thumbnail representation of this imageset.
tile_levels	The number of levels of tiling.
url	The URL of the image data.
width_factor	This is a legacy parameter.
xmeta	XML metadata - a namespace object for attaching arbitrary text to serialize

Methods Summary

add_traits(**traits)	Dynamically add trait attributes to the HasTraits instance.
apply_to_xml(elem)	Serialize the data of this object to an existing XML tree
class_own_trait_events(name)	Get a dict of all event handlers defined on this class, not a parent.
class_own_traits(**metadata)	Get a dict of all the traitlets defined on this class, not a parent.
class_trait_names(**metadata)	Get a list of all the names of this class' traits.
class_traits(**metadata)	Get a dict of all the traits of this class.
from_file(path[, encoding])	Deserialize an instance of this class from an XML file on local disk.
from_text(text)	Deserialize an instance of this class from XML-formatted text.
from_url(url[, session])	Deserialize an instance of this class from XML downloaded from the specified URL.
from_xml(elem)	Deserialize an instance of this class from XML.
has_trait(name)	Returns True if the object has a trait with the specified name.
hold_trait_notifications()	Context manager for bundling trait change notifications and cross validation.
mutate_urls(mutator)	Visit all URLs inside this container and potentially mutate them.
notify_change(change)	Notify observers of a change event
observe(handler[, names, type])	Setup a handler to be called when a trait changes.
on_trait_change([handler, name, remove])	DEPRECATED: Setup a handler to be called when a trait changes.
set_position_from_wcs(headers, width, height)	Set the positional information associated with this imageset to match a set of WCS headers.
set_trait(name, value)	Forcibly sets trait attribute, including read-only attributes.
setup_instance(**kwargs)	This is called before self.__init__ is called.
to_xml()	Serialize this object to XML.
to_xml_string([indent])	Serialize this object to XML text.
trait_defaults(*names, **metadata)	Return a trait's default value or a dictionary of them
trait_events([name])	Get a dict of all the event handlers of this class.
trait_has_value(name)	Returns True if the specified trait has a value.
trait_metadata(traitname, key[, default])	Get metadata values for trait by key.
trait_names(**metadata)	Get a list of all the names of this class' traits.
trait_values(**metadata)	A dict of trait names and their values.
traits(**metadata)	Get a dict of all the traits of this class.
unobserve(handler[, names, type])	Remove a trait change handler.
unobserve_all([name])	Remove trait change handlers of any type for the specified name.
wcs_headers_from_position([height])	Compute a set of WCS headers for this ImageSet's positional information.
write_xml(dest_stream[, dest_wants_bytes, ...])	Serialize this object to XML, writing the data to a stream.

Attributes Documentation

alt_url

An alternative URL that provided the data.

If provided and the Windows client attempts to load an imageset using this alternative URL, that imageset will be replaced by this one. This provides a mechanism for superseding old imagesets with improved versions.

band_pass

The bandpass of the image data.

base_degrees_per_tile

The angular scale of the image.

For untiled images, this is the pixel scale: the number of degrees per pixel in the vertical direction. Non-square pixels are not supported.

For tiled images, this is the angular height of the image, in degrees, after its dimensions have been padded out to the next largest power of 2 for tiling purposes. If a square image is 1200 pixels tall and has a height of 0.016 deg, the padded height would be 2048 pixels and this parameter should be set to 0.016 * 2048 / 1200 = 0.0273.

base_tile_level

The level of the highest (coarsest-resolution) tiling available.

This should be zero except for special circumstances.

bottoms_up

The parity of the image’s projection on the sky.

For untiled (projection = SkyImage) images, this flag defines the image’s parity, which basically sets whether the image needs to be flipped during rendering. This field should be False for typical RGB color images that map onto the sky as if you had taken them with a digital camera. For these images, the first row of image data is at the top of the image at zero rotation. For typical FITS files, on the other hand, the first row of image data is at the bottom of the image, which results in a parity inversion. In these cases, the bottoms_up flag should be True (hence its name). In the terminology of Astrometry.Net, bottoms_up = False corresponds to negative parity, and bottoms_up = True corresponds to positive parity.

The effect of setting this flag to True is to effectively flip the image and its coordinate system left-to-right. For a bottoms_up = False image with offset_x, offset_y, and rotation_deg all zero, the lower-left corner of the image lands at the center_x and center_y, and positive rotations rotate the image counter-clockwise around that origin. If you take the same image and make bottoms_up = True, the image will appear to have been flipped left-to-right, the lower-right corner of the image will land at the coordinate center, and positive rotations will rotate it clockwise around that origin. In both cases, positive values of offset_x and offset_y move the center of the image closer to the coordinate center, but when bottoms_up = False, this means that the image is moving down and left, and when bottoms_up = True this means that the image is moving down and right.

For tiled images (projection = Tan), this field must be false. If it is true, the imageset won’t render.

center_x

The horizontal location of the center of the image’s projection coordinate system.

For sky images, this is a right ascension in degrees. Note that this parameter just helps to define a coordinate system; it does not control how the actual image data are placed onto that coordinate system. The offset_x and offset_y parameters do that.

center_y

The vertical location of the center of the image’s projection coordinate system.

For sky images, this is a declination in degrees. Note that this parameter just helps to define a coordinate system; it does not control how the actual image data are placed onto that coordinate system. The offset_x and offset_y parameters do that.

credits

Textual credits for the image originator.

credits_url

A URL giving the source of the image or more information about its creation.

cross_validation_lock

A contextmanager for running a block with our cross validation lock set to True.

At the end of the block, the lock’s value is restored to its value prior to entering the block.

data_max

Highest data value of a FITS file.

data_min

Lowest data value of a FITS file.

data_set_type

The renderer mode to which these data apply.

Possible values are "Earth", "Planet", "Sky", "Panorama", "SolarSystem", and "Sandbox".

dem_url

The URL of the DEM data.

Either a URL or a URL template. TODO: details

description

A textual description of the imagery.

This field is referenced a few times in the original WWT documentation, but is not actually implemented. The Place.description field is at least loaded from the XML.

elevation_model

TBD.

file_type

The extension(s) of the image file(s) in this set.

In the simplest case, this field will contain an image filetype extension including the leading period, such as .jpeg or .png. Some datasets in the wild lack the leading period: they have just png or something similar. The value .auto is also used in some cases, which can be OK because often WWT doesn’t actually use this field for any particular purpose.

Some datasets, like HiPS imagery, provide multiple filetypes simultaneously. These can be expressed by including several filename extensions separated by spaces. For instance, png jpeg fits. The existing WTML records that support multiple filetypes do not include any leading periods, but clients should be prepared for them to be present.

Imagesets to be rendered as FITS data must have the exact value .fits for this field. If multiple filetypes are specified, the special FITS-rendering machinery will not be invoked. This is true for both single FITS files and tiled FITS imagesets, including HiPS FITS datasets.

A supported filetype extension of tsv (or .tsv) means that this “imageset” actually contains a HiPS progressive catalog, not bitmap imagery. Imageset records should not intermix image-type and catalog-type filetypes. (We don’t know if there are any examples in the wild of HiPS datasets that claim to contain both kinds of data.)

generic

TBD.

mean_radius

TBD.

msr_community_id

The ID number of the WWT Community that this content came from.

msr_component_id

The ID number of this content item on the WWT Communities system.

name

A name used to refer to this imageset.

Various parts of the WWT internals reference imagesets by this name, so it should be distinctive.

offset_x

The horizontal positioning of the image relative to its projection coordinate system.

For untiled sky images with bottoms_up false, the image is by default positioned such that its lower left corner lands at the center of the projection coordinate system (namely, center_x and center_y). The offset is measured in pixels and moves the image leftwards. Therefore, offset_x = image_width / 2 places the horizontal center of the image at center_x. This parameter is therefore analogous to the WCS keyword CRVAL1.

For untiled sky images where bottoms_up is true, the X coordinate system has been mirrored. Therefore when this field is zero, the lower right corner of the image will land at the center of the projection coordinate system, and positive values will move the image to the right.

For tiled sky images, the offset is measured in degrees, and a value of zero means that the center of the image lands at the center of the projection coordinate system. Increasingly positive values move the image to the right.

As per the usual practice, offsets are always along the horizontal axis of the image in question, regardless of its rotation on the sky.

offset_y

The vertical positioning of the image relative to its projection coordinate system.

For untiled sky images with bottoms_up false, the image is by default positioned such that its lower left corner lands at the center of the projection coordinate system (namely, center_x and center_y). The offset is measured in pixels and moves the image downwards. Therefore, offset_y = image_height / 2 places the vertical center of the image at center_y. This parameter is therefore analogous to the WCS keyword CRVAL2.

For untiled sky images where bottoms_up is true, the X coordinate system has been mirrored but the Y coordinate system is the same. Therefore when this field is zero, the lower right corner of the image will land at the center of the projection coordinate system, but positive values will still move the image downwards.

For tiled sky images, the offset is measured in degrees, and a value of zero means that the center of the image lands at the center of the projection coordinate system. Increasingly positive values move the image upwards.

As per the usual practice, offsets are always along the vertical axis of the image in question, regardless of its rotation on the sky.

permission

TBD.

pixel_cut_high

Suggested default high cutoff value when displaying FITS.

pixel_cut_low

Suggested default low cutoff value when displaying FITS.

projection

The type of projection used to place this image on the sky.

For untiled images, this should be “SkyImage”. For tiled images, it should be “Tan”. The set_position_from_wcs() method will set this value appropriately based on tile_levels.

quad_tree_map

TBD.

reference_frame

TBD.

rmeta

Runtime metadata - a namespace object for attaching arbitrary extra information

rotation_deg

The rotation of image’s projection coordinate system, in degrees.

For sky images with bottoms_up false, this is East from North, i.e. counterclockwise. If bottoms_up is true (only allowed for untiled images), the image coordinate system is mirrored, and positive rotations rotate the image clockwise relative to the sky.

sparse

TBD.

stock_set

TBD.

thumbnail_url

A URL to a standard WWT thumbnail representation of this imageset.

tile_levels

The number of levels of tiling.

Should be zero for untiled images (projection = ProjectionType.SkyImage).

For tiled images (projection = ProjectionType.Tan), an image with tile_levels = 1 has been broken into four tiles, each 256x256 pixels. For tile_levels = 2, there are sixteen tiles, and the padded height of the tiled area is 256 * 2**2 = 1024 pixels. Image with dimensions of 2048 pixels or smaller do not need to be tiled, so if this parameter is nonzero it will usually be 4 or larger.

url

The URL of the image data.

Either a URL or a URL template. URLs that are exposed to the engine should be absolute and use the http:// protocol (the web engine will rewrite them to HTTPS if needed). The wwtdatatool program that comes with this package provides some helpful utilities to allow data-processing to use relative URLs. TODO: more details.

width_factor

This is a legacy parameter. Leave it at 2.

xmeta

XML metadata - a namespace object for attaching arbitrary text to serialize

Methods Documentation

add_traits(**traits: Any) → None

Dynamically add trait attributes to the HasTraits instance.

apply_to_xml(elem)

Serialize the data of this object to an existing XML tree

Parameters:

elemxml.etree.ElementTree.Element

An XML subtree that will be filled in with data values associated with this instance.

Returns:

self

Notes

This method makes it possible to work with input data that may have additional contents not defined in the WWT specification – by modifying the existing tree, we can preserve those data.

classmethod class_own_trait_events(name: str) → dict[str, EventHandler]

Get a dict of all event handlers defined on this class, not a parent.

Works like event_handlers, except for excluding traits from parents.

classmethod class_own_traits(**metadata: Any) → dict[str, traitlets.TraitType[Any, Any]]

Get a dict of all the traitlets defined on this class, not a parent.

Works like class_traits, except for excluding traits from parents.

classmethod class_trait_names(**metadata: Any) → list[str]

Get a list of all the names of this class’ traits.

This method is just like the trait_names() method, but is unbound.

classmethod class_traits(**metadata: Any) → dict[str, traitlets.TraitType[Any, Any]]

Get a dict of all the traits of this class. The dictionary is keyed on the name and the values are the TraitType objects.

This method is just like the traits() method, but is unbound.

The TraitTypes returned don’t know anything about the values that the various HasTrait’s instances are holding.

The metadata kwargs allow functions to be passed in which filter traits based on metadata values. The functions should take a single value as an argument and return a boolean. If any function returns False, then the trait is not included in the output. If a metadata key doesn’t exist, None will be passed to the function.

classmethod from_file(path, encoding='utf-8-sig')

Deserialize an instance of this class from an XML file on local disk.

Parameters:

pathstring

The path of the XML file.

encodingoptional string, default “utf-8-sig”

The encoding of the file text. The default value is basically UTF-8 but will ignore Windows Byte Order Markers (BOMs) if present.

Returns:

An instance of the class, initialized with data from the XML.

classmethod from_text(text)

Deserialize an instance of this class from XML-formatted text.

Parameters:

textstring

The XML text.

Returns:

An instance of the class, initialized with data from the XML.

classmethod from_url(url, session=None, **kwargs)

Deserialize an instance of this class from XML downloaded from the specified URL.

Parameters:

urlstring

The URL from which to download the XML.

sessionrequests session or None (the default)

The HTTP communications session to use.

kwargs

Extra arguments to pass to requests.get.

Returns:

An instance of the class, initialized with data from the XML.

classmethod from_xml(elem)

Deserialize an instance of this class from XML.

Parameters:

elemxml.etree.ElementTree.Element

An XML element serializing the object.

Returns:

An instance of the class, initialized with data from the XML.

has_trait(name: str) → bool

Returns True if the object has a trait with the specified name.

hold_trait_notifications() → Any

Context manager for bundling trait change notifications and cross validation.

Use this when doing multiple trait assignments (init, config), to avoid race conditions in trait notifiers requesting other trait values. All trait notifications will fire after all values have been assigned.

mutate_urls(mutator)

Visit all URLs inside this container and potentially mutate them.

Parameters:

mutatorcallable(str) -> str

A function taking a URL string and returning a URL string.

Notes

For each URL inside the container, the URL is updated with the mutator’s return value:

this.some_url = mutator(this.some_url)

If you just want to visit all of the URLs inside this container, you can write a mutator the returns its input unmodified.

Implementors should not call the mutator if the URL is an optional parameter that is None (or otherwise unset).

notify_change(change: Bunch) → None

Notify observers of a change event

observe(handler: Callable[[...], Any], names: Sentinel | str | Iterable[Sentinel | str] = traitlets.All, type: Sentinel | str = 'change') → None

Setup a handler to be called when a trait changes.

This is used to setup dynamic notifications of trait changes.

Parameters:

handlercallable

A callable that is called when a trait changes. Its signature should be handler(change), where change is a dictionary. The change dictionary at least holds a ‘type’ key. * type: the type of notification. Other keys may be passed depending on the value of ‘type’. In the case where type is ‘change’, we also have the following keys: * owner : the HasTraits instance * old : the old value of the modified trait attribute * new : the new value of the modified trait attribute * name : the name of the modified trait attribute.

nameslist, str, All

If names is All, the handler will apply to all traits. If a list of str, handler will apply to all names in the list. If a str, the handler will apply just to that name.

typestr, All (default: ‘change’)

The type of notification to filter by. If equal to All, then all notifications are passed to the observe handler.

on_trait_change(handler: EventHandler | None = None, name: Sentinel | str | None = None, remove: bool = False) → None

DEPRECATED: Setup a handler to be called when a trait changes.

This is used to setup dynamic notifications of trait changes.

Static handlers can be created by creating methods on a HasTraits subclass with the naming convention ‘_[traitname]_changed’. Thus, to create static handler for the trait ‘a’, create the method _a_changed(self, name, old, new) (fewer arguments can be used, see below).

If remove is True and handler is not specified, all change handlers for the specified name are uninstalled.

Parameters:

handlercallable, None

A callable that is called when a trait changes. Its signature can be handler(), handler(name), handler(name, new), handler(name, old, new), or handler(name, old, new, self).

namelist, str, None

If None, the handler will apply to all traits. If a list of str, handler will apply to all names in the list. If a str, the handler will apply just to that name.

removebool

If False (the default), then install the handler. If True then unintall it.

set_position_from_wcs(headers, width, height, place=None, fov_factor=1.7)

Set the positional information associated with this imageset to match a set of WCS headers.

Parameters:

headersHeader or string-keyed dict-like

A set of FITS-like headers including WCS keywords such as CRVAL1.

widthpositive integer

The width of the image associated with the WCS, in pixels.

heightpositive integer

The height of the image associated with the WCS, in pixels.

placeoptional Place

If specified, the centering and zoom level of the Place object will be set to match the center and size of this image.

fov_factoroptional

If place is provided, its zoom level will be set so that the angular height of the client viewport is this factor times the angular height of the image. The default is 1.7.

Returns:

self

For convenience in chaining function calls.

Notes

Certain of the ImageSet parameters take on different meanings depending on whether the image in question is a tiled “study” or not. This method will alter its behavior depending on whether the tile_levels attribute is greater than zero. Make sure that this parameter has acquired its final value before calling this function.

For the time being, the WCS must be equatorial using the gnomonic (TAN) projection.

This function may be used when the imageset projection is TOAST. However, in this case most of the WCS parameters are irrelevant. The WCS information is only used to apply basic centering and sizing settings.

Required keywords in headers are:

• CTYPE1 and CTYPE2

• CRVAL1 and CRVAL2

• CRPIX1 and CRPIX2

• Either:

  • CD1_1, CD2_2 (preferred) or

  • CDELT1, CDELT2, PC1_1, and PC1_2;

If present PC1_2, PC2_1, CD1_2, and/or CD2_1 are used. If absent, they are assumed to be zero.

This routine assumes that the WCS coordinates have the correct parity for the data that they describe. If these WCS coordinates describe a JPEG-like image, the parity of the coordinates should be negative (“top-down”), which means that the determinant of the CD matrix should have a positive sign. If these coordinates describe a FITS-like image, the parity should be positive or “bottoms-up”, with a negative determinant of the CD matrix. If the image in question is tiled, the parity must be top-down, in the sense the bottoms-up tiled imagery just won’t render in the engine. There are some CD matrices that can’t be expressed in WWT’s formalism (rotation, scale, parity) and this method will do its best to detect and reject them.

set_trait(name: str, value: Any) → None

Forcibly sets trait attribute, including read-only attributes.

setup_instance(**kwargs: Any) → None

This is called before self.__init__ is called.

to_xml()

Serialize this object to XML.

Returns:

elemxml.etree.ElementTree.Element

An XML element serializing the object.

to_xml_string(indent=True)

Serialize this object to XML text.

Parameters:

indentoptional bool, default True

Whether the returned XML text will have user-friendly indentation or not.

Returns:

xml_textstring

A textual serialization of the object as XML.

trait_defaults(*names: str, **metadata: Any) → dict[str, Any] | Sentinel

Return a trait’s default value or a dictionary of them

Notes

Dynamically generated default values may depend on the current state of the object.

classmethod trait_events(name: str | None = None) → dict[str, EventHandler]

Get a dict of all the event handlers of this class.

Parameters:

namestr (default: None)

The name of a trait of this class. If name is None then all the event handlers of this class will be returned instead.

Returns:

The event handlers associated with a trait name, or all event handlers.

trait_has_value(name: str) → bool

Returns True if the specified trait has a value.

This will return false even if getattr would return a dynamically generated default value. These default values will be recognized as existing only after they have been generated.

Example

class MyClass(HasTraits):
    i = Int()

mc = MyClass()
assert not mc.trait_has_value("i")
mc.i  # generates a default value
assert mc.trait_has_value("i")

trait_metadata(traitname: str, key: str, default: Any | None = None) → Any

Get metadata values for trait by key.

trait_names(**metadata: Any) → list[str]

Get a list of all the names of this class’ traits.

trait_values(**metadata: Any) → dict[str, Any]

A dict of trait names and their values.

The metadata kwargs allow functions to be passed in which filter traits based on metadata values. The functions should take a single value as an argument and return a boolean. If any function returns False, then the trait is not included in the output. If a metadata key doesn’t exist, None will be passed to the function.

Returns:

A dict of trait names and their values.

Notes

Trait values are retrieved via getattr, any exceptions raised by traits or the operations they may trigger will result in the absence of a trait value in the result dict.

traits(**metadata: Any) → dict[str, traitlets.TraitType[Any, Any]]

Get a dict of all the traits of this class. The dictionary is keyed on the name and the values are the TraitType objects.

The TraitTypes returned don’t know anything about the values that the various HasTrait’s instances are holding.

The metadata kwargs allow functions to be passed in which filter traits based on metadata values. The functions should take a single value as an argument and return a boolean. If any function returns False, then the trait is not included in the output. If a metadata key doesn’t exist, None will be passed to the function.

unobserve(handler: Callable[[...], Any], names: Sentinel | str | Iterable[Sentinel | str] = traitlets.All, type: Sentinel | str = 'change') → None

Remove a trait change handler.

This is used to unregister handlers to trait change notifications.

Parameters:

handlercallable

The callable called when a trait attribute changes.

nameslist, str, All (default: All)

The names of the traits for which the specified handler should be uninstalled. If names is All, the specified handler is uninstalled from the list of notifiers corresponding to all changes.

typestr or All (default: ‘change’)

The type of notification to filter by. If All, the specified handler is uninstalled from the list of notifiers corresponding to all types.

unobserve_all(name: str | Any = traitlets.All) → None

Remove trait change handlers of any type for the specified name. If name is not specified, removes all trait notifiers.

wcs_headers_from_position(height=None)

Compute a set of WCS headers for this ImageSet’s positional information.

Parameters:

heightoptional int

The height of the underlying image, in pixels. This quantity is needed to compute WCS headers correctly for untiled (SKY_IMAGE projection) images. If this quantity is needed but not provided, a ValueError will be raised. Note that the ImageSet class does not store this quantity.

Returns:

A string-keyed dict-like containing FITS/WCS header keywords such as

CTYPE1, CRPIX1, etc.

Notes

At the moment, this function only works for ImageSets with a projection type of SKY_IMAGE. Support for other projections might be added later, if the need arises. Note, however, that tiled images have their sizes adjusted to be powers of 2, and the “actual” size of the source imagery is not necessarily preserved.

write_xml(dest_stream, dest_wants_bytes=False, indent=True)

Serialize this object to XML, writing the data to a stream.

Parameters:

dest_streamwriteable file-like object or None

The destination to which the XML data will be written. If None, standard output is used.

dest_wants_bytesoptional bool, default False

Whether the destination stream expects to be fed bytes data rather than Unicode. If so, the XML text is encoded into UTF-8 before being written.

indentbool, default True

Whether the returned XML text will have user-friendly indentation or not.

Returns:

None