HelioviewerClient

class sunpy.net.helioviewer.HelioviewerClient(url='https://api.helioviewer.org/')[source] [edit on github]

Bases: object

Helioviewer.org Client

Parameters

url (str) – Default URL points to the Helioviewer API.

Attributes Summary

data_sources

We trawl through the return from getDataSources to create a clean dictionary for all available sourceIDs.

Methods Summary

download_jp2(date[, observatory, …])

Downloads the JPEG 2000 that most closely matches the specified time and data source.

download_png(date, image_scale, layers[, …])

Downloads the PNG that most closely matches the specified time and data source.

get_closest_image(date[, observatory, …])

Finds the closest image available for the specified source and date.

get_data_sources()

Return a hierarchical dictionary of the available datasources on helioviewer.org.

get_jp2_header(date[, observatory, …])

Get the XML header embedded in a JPEG2000 image.

is_online()

Returns True if Helioviewer is online and available.

Attributes Documentation

data_sources

We trawl through the return from getDataSources to create a clean dictionary for all available sourceIDs.

Here is a list of all of them: https://api.helioviewer.org/docs/v2/#appendix_datasources

Methods Documentation

download_jp2(date, observatory=None, instrument=None, detector=None, measurement=None, source_id=None, directory=None, overwrite=False)[source] [edit on github]

Downloads the JPEG 2000 that most closely matches the specified time and data source. We can use observatory and measurement or instrument and measurement to get the value for source ID which can then be used to get required information. This uses getJP2Image from the Helioviewer API.

Note

We can use observatory and measurement or instrument and measurement to get the value for source ID which can then be used to get required information.

Parameters
  • date (astropy.time.Time, str) – A string or Time object for the desired date of the image

  • observatory (str) – Observatory name

  • instrument (str) – Instrument name

  • measurement (str) – Measurement name

  • detector (str) – Detector name

  • source_id (int) – ID number for the required instrument/measurement. This can be used directly instead of using the previous parameters.

  • directory (str) – Directory to download JPEG 2000 image to.

  • overwrite (bool) – Defaults to False. If set to True, will overwrite any files with the same name.

Returns

out (str) – Returns a filepath to the downloaded JPEG 2000 image.

Examples

>>> import sunpy.map
>>> from sunpy.net import helioviewer
>>> hv = helioviewer.HelioviewerClient()  # doctest: +REMOTE_DATA
>>> filepath = hv.download_jp2('2012/07/03 14:30:00', observatory='SDO',
...                            instrument='HMI', detector=None, measurement='continuum')  # doctest: +REMOTE_DATA
>>> filepath = hv.download_jp2('2012/07/03 14:30:00', observatory='SDO', measurement='continuum')  # doctest: +REMOTE_DATA
>>> filepath = hv.download_jp2('2012/07/03 14:30:00', instrument='HMI', measurement='continuum')  # doctest: +REMOTE_DATA
>>> aia = sunpy.map.Map(filepath)  # doctest: +REMOTE_DATA
>>> aia.peek()  # doctest: +SKIP
download_png(date, image_scale, layers, directory=None, overwrite=False, watermark=False, events='', event_labels=False, scale=False, scale_type='earth', scale_x=0, scale_y=0, width=4096, height=4096, x0=0, y0=0, x1=None, y1=None, x2=None, y2=None)[source] [edit on github]

Downloads the PNG that most closely matches the specified time and data source.

This function is different to download_jp2. Here you get PNG images and return more complex images.

For example you can return an image that has multiple layers composited together from different sources. Also mark solar features/events with an associated text label. The image can also be cropped to a smaller field of view.

These parameters are not pre-validated before they are passed to Helioviewer API. See https://api.helioviewer.org/docs/v2/#appendix_coordinates for more information about what coordinates values you can pass into this function.

This uses takeScreenshot from the Helioviewer API.

Note

Parameters x1, y1, x2 and y2 are set to None. If all 4 are set to values, then keywords: width, height, x0, y0 will be ignored.

Parameters
  • date (astropy.time.Time, str) – A parse_time parsable string or Time object for the desired date of the image

  • image_scale (float) – The zoom scale of the image in arcseconds per pixel. For example, the scale of an AIA image is 0.6.

  • layers (str) – Image datasource layer/layers to include in the screeshot. Each layer string is comma-separated with either: “[sourceId,visible,opacity]” or “[obs,inst,det,meas,visible,opacity]”. Multiple layers are: “[layer1],[layer2],[layer3]”.

  • events (str, optional) – Defaults to an empty string to indicate no feature/event annotations. List feature/event types and FRMs to use to annoate the image. Example could be “[AR,HMI_HARP;SPoCA,1]” or “[CH,all,1]”

  • event_labels (bool, optional) – Defaults to False. Annotate each event marker with a text label.

  • watermark (bool, optional) – Defaults to False. Overlay a watermark consisting of a Helioviewer logo and the datasource abbreviation(s) and timestamp(s) in the screenshot.

  • directory (str, optional) – Directory to download JPEG 2000 image to.

  • overwrite (bool, optional) – Defaults to False. If set to True, will overwrite any files with the same name.

  • scale (bool, optional) – Defaults to False. Overlay an image scale indicator.

  • scale_type (str, optional) – Defaults to Earth. What is the image scale indicator will be.

  • scale_x (int, optional) – Defaults to 0 (i.e, in the middle) Horizontal offset of the image scale indicator in arcseconds with respect to the center of the Sun.

  • scale_y (int, optional) – Defaults to 0 (i.e, in the middle) Vertical offset of the image scale indicator in arcseconds with respect to the center of the Sun.

  • x0 (float, optional) – The horizontal offset from the center of the Sun.

  • y0 (float, optional) – The vertical offset from the center of the Sun.

  • width (int, optional) – Defaults to 4096. Width of the image in pixels.

  • height (int, optional) – Defaults to 4096. Height of the image in pixels.

  • x1 (float, optional) – Defaults to None The offset of the image’s left boundary from the center of the sun, in arcseconds.

  • y1 (float, optional) – Defaults to None The offset of the image’s top boundary from the center of the sun, in arcseconds.

  • x2 (float, optional) – Defaults to None The offset of the image’s right boundary from the center of the sun, in arcseconds.

  • y2 (float, optional) – Defaults to None The offset of the image’s bottom boundary from the center of the sun, in arcseconds.

Returns

out (str) – Returns a filepath to the downloaded PNG image.

Examples

>>> from sunpy.net.helioviewer import HelioviewerClient
>>> hv = HelioviewerClient()  # doctest: +REMOTE_DATA
>>> file = hv.download_png('2012/07/16 10:08:00', 2.4,
...                        "[SDO,AIA,AIA,171,1,100]",
...                        x0=0, y0=0, width=1024, height=1024)   # doctest: +REMOTE_DATA
>>> file = hv.download_png('2012/07/16 10:08:00', 4.8,
...                        "[SDO,AIA,AIA,171,1,100],[SOHO,LASCO,C2,white-light,1,100]",
...                        x1=-2800, x2=2800, y1=-2800, y2=2800)   # doctest: +REMOTE_DATA
get_closest_image(date, observatory=None, instrument=None, detector=None, measurement=None, source_id=None)[source] [edit on github]

Finds the closest image available for the specified source and date. This does not download any file.

This uses getClosestImage from the Helioviewer API.

Note

We can use observatory and measurement or instrument and measurement to get the value for source ID which can then be used to get required information.

Parameters
  • date (astropy.time.Time, str) – A parse_time parsable string or Time object for the desired date of the image

  • observatory (str) – Observatory name

  • instrument (str) – Instrument name

  • detector (str) – Detector name

  • measurement (str) – Measurement name

  • source_id (int) – ID number for the required instrument/measurement. This can be used directly instead of using the previous parameters.

Returns

out (dict) – A dictionary containing meta-information for the closest image matched

Examples

>>> from sunpy.net import helioviewer
>>> client = helioviewer.HelioviewerClient()  # doctest: +REMOTE_DATA
>>> metadata = client.get_closest_image('2012/01/01', source_id=11)  # doctest: +REMOTE_DATA
>>> print(metadata['date'])  # doctest: +REMOTE_DATA
2012-01-01T00:00:07.000
get_data_sources()[source] [edit on github]

Return a hierarchical dictionary of the available datasources on helioviewer.org.

This uses getDataSources from the Helioviewer API.

Returns

out (dict) – A dictionary containing meta-information for each data source that Helioviewer supports.

get_jp2_header(date, observatory=None, instrument=None, detector=None, measurement=None, jp2_id=None)[source] [edit on github]

Get the XML header embedded in a JPEG2000 image. Includes the FITS header as well as a section of Helioviewer-specific metadata. We can use observatory and measurement or instrument and measurement to get the value for source ID which can then be used to get required information. This uses getJP2Header from the Helioviewer API.

Note

We can use observatory and measurement or instrument and measurement to get the value for source ID which can then be used to get required information.

Parameters
  • date (astropy.time.Time, str) – A parse_time parsable string or Time object for the desired date of the image

  • observatory (str) – Observatory name

  • instrument (str) – Instrument name

  • measurement (str) – Measurement name

  • detector (str) – Detector name

  • jp2_id (int) – Unique JP2 image identifier. This can be used directly instead of using the previous parameters.

Returns

out (dict) – Returns a dictionary containing the header information of JPEG 2000 image. The returned dictionary may have either one or two keys: fits and helioviewer.

Examples

>>> from sunpy.net import helioviewer
>>> hv = helioviewer.HelioviewerClient()  # doctest: +REMOTE_DATA
>>> header = hv.get_jp2_header('2012/07/03', observatory='SDO',
...                            instrument='HMI', detector=None, measurement='continuum')  # doctest: +REMOTE_DATA
>>> # The key 'fits' can be used to get the fits header information
>>> fits_header = header['fits']  # doctest: +REMOTE_DATA
>>> # The keys 'helioviewer' can be used to extract the helioviewer specific metadata.
>>> helioviewer_meta_data = header['helioviewer']  # doctest: +REMOTE_DATA
is_online()[source] [edit on github]

Returns True if Helioviewer is online and available.