Regions

class regions.Regions(regions=(), /)

Bases: object

Class to hold a list of Region objects.

This class provides a unified I/O interface that supports reading, writing, parsing, and serializing many region data formats.

Parameters:

regionslist of Region

The list of region objects.

Methods Summary

append(region)	Append the region to the end of the list of regions.
copy()	Return a shallow copy of this object.
extend(regions)	Extend the list of regions by appending elements from the input regions.
get_formats()	Get the registered I/O formats as a Table.
insert(index, region)	Insert the region before index.
parse(data[, format])	Parse a region string or table and return as a Regions object.
pop([index])	Remove and return the region at index.
read(filename[, format, cache])	Read and parse a region file and return as a Regions object.
reverse()	Reverse the list of regions in place.
serialize([format])	Serialize the regions to a region string or table.
write(filename[, format, overwrite])	Write the regions to a region file in the specified format.

Methods Documentation

append(region)

Append the region to the end of the list of regions.

Parameters:

regionRegion

The region to append.

copy()

Return a shallow copy of this object.

extend(regions)

Extend the list of regions by appending elements from the input regions.

Parameters:

regionsRegions or list of Region

A Regions object or a list of regions to include.

classmethod get_formats()

Get the registered I/O formats as a Table.

insert(index, region)

Insert the region before index.

Parameters:

indexint

The list index.

regionRegion

The region to insert.

classmethod parse(data, format=None, **kwargs)

Parse a region string or table and return as a Regions object.

This method allows parsing region data in many supported data formats, e.g.,:

>>> from regions import Regions
>>> reg1 = Regions.parse(regions_str, format='ds9')
>>> reg2 = Regions.parse(regions_str, format='crtf')
>>> reg3 = Regions.parse(regions_tbl, format='fits')

A list of the available formats for Regions is available using:

>>> Regions.get_formats()

Parameters:

datastr or Table

The region data to parse.

formatstr, optional

The file format specifier.

**kwargsdict, optional

Keyword arguments passed to the data parser.

Returns:

resultRegions

A Regions object containing the data contents.

pop(index=-1)

Remove and return the region at index.

Parameters:

indexint, optional

The index of the region to remove.

Returns:

resultRegion

classmethod read(filename, format=None, cache=False, **kwargs)

Read and parse a region file and return as a Regions object.

This method allows reading a file in many supported data formats, e.g.,:

>>> from regions import Regions
>>> reg1 = Regions.read('regions.reg', format='ds9')
>>> reg2 = Regions.read('regions.crtf', format='crtf')
>>> reg3 = Regions.read('regions.fits', format='fits')

A list of the available formats for Regions is available using:

>>> Regions.get_formats()

Parameters:

filenamestr

The filename or URL of the file to read.

formatstr, optional

The file format specifier.

cachebool or ‘update’, optional

Whether to cache the contents of remote URLs. If ‘update’, check the remote URL for a new version but store the result in the cache.

**kwargsdict, optional

Keyword arguments passed to the data reader.

Returns:

resultRegions

A Regions object containing the file contents.

reverse()

Reverse the list of regions in place.

serialize(format=None, **kwargs)

Serialize the regions to a region string or table.

This method allows serializing regions in many supported data formats, e.g.,:

>>> from regions import Regions
>>> reg = Regions.read('regions.reg', format='ds9')
>>> reg1_str = reg.serialize(format='ds9')
>>> reg2_str = reg.serialize(format='crtf')
>>> reg3_tbl = reg.serialize(format='fits')

A list of the available formats for Regions is available using:

>>> Regions.get_formats()

Parameters:

formatstr, optional

The file format specifier.

**kwargsdict, optional

Keyword arguments passed to the data serializer.

write(filename, format=None, overwrite=False, **kwargs)

Write the regions to a region file in the specified format.

This method allows writing a file in many supported data formats, e.g.,:

>>> from regions import Regions
>>> reg = Regions.read('regions.reg', format='ds9')
>>> reg.write('new_regions.reg', format='ds9')
>>> reg.write('new_regions.crtf', format='crtf')
>>> reg.write('new_regions.fits', format='fits')

A list of the available formats for Regions is available using:

>>> Regions.get_formats()

Parameters:

filenamestr

The filename or URL of the file to write.

formatstr, optional

The file format specifier.

overwritebool, optional

If True, overwrite the output file if it exists. Raises an OSError if False and the output file exists. Default is False.

**kwargsdict, optional

Keyword arguments passed to the data writer.