| Name | xisf JSON |
| Version |
0.9.5
JSON |
| download |
| home_page | |
| Summary | Encoder/Decoder for XISF (Extensible Image Serialization Format) |
| upload_time | 2024-03-02 11:26:51 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.6 |
| license | GNU General Public License v3 (GPLv3) |
| keywords |
astronomy
xisf
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<a id="xisf"></a>
# xisf
XISF Encoder/Decoder (see https://pixinsight.com/xisf/).
This implementation is not endorsed nor related with PixInsight development team.
Copyright (C) 2021-2022 Sergio Díaz, sergiodiaz.eu
This program is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, version 3 of the License.
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.
You should have received a copy of the GNU General Public License along with
this program. If not, see <http://www.gnu.org/licenses/>.
<a id="xisf.XISF"></a>
## XISF Objects
```python
class XISF()
```
Implements an baseline XISF Decoder and a simple baseline Encoder.
It parses metadata from Image and Metadata XISF core elements. Image data is returned as a numpy ndarray
(using the "channels-last" convention by default).
What's supported:
- Monolithic XISF files only
- XISF data blocks with attachment, inline or embedded block locations
- Planar pixel storage models, *however it assumes 2D images only* (with multiple channels)
- UInt8/16/32 and Float32/64 pixel sample formats
- Grayscale and RGB color spaces
- Decoding:
- multiple Image core elements from a monolithic XISF file
- Support all standard compression codecs defined in this specification for decompression
(zlib/lz4[hc]/zstd + byte shuffling)
- Encoding:
- Single image core element with an attached data block
- Support all standard compression codecs defined in this specification for decompression
(zlib/lz4[hc]/zstd + byte shuffling)
- "Atomic" properties (scalar types, String, TimePoint), Vector and Matrix (e.g. astrometric solutions)
- Metadata and FITSKeyword core elements
What's not supported (at least by now):
- Read pixel data in the normal pixel storage models
- Read pixel data in the planar pixel storage models other than 2D images
- Complex and Table properties
- Any other not explicitly supported core elements (Resolution, Thumbnail, ICCProfile, etc.)
Usage example:
```
from xisf import XISF
import matplotlib.pyplot as plt
xisf = XISF("file.xisf")
file_meta = xisf.get_file_metadata()
file_meta
ims_meta = xisf.get_images_metadata()
ims_meta
im_data = xisf.read_image(0)
plt.imshow(im_data)
plt.show()
XISF.write(
"output.xisf", im_data,
creator_app="My script v1.0", image_metadata=ims_meta[0], xisf_metadata=file_meta,
codec='lz4hc', shuffle=True
)
```
If the file is not huge and it contains only an image (or you're interested just in one of the
images inside the file), there is a convenience method for reading the data and the metadata:
```
from xisf import XISF
import matplotlib.pyplot as plt
im_data = XISF.read("file.xisf")
plt.imshow(im_data)
plt.show()
```
The XISF format specification is available at https://pixinsight.com/doc/docs/XISF-1.0-spec/XISF-1.0-spec.html
<a id="xisf.XISF.__init__"></a>
#### \_\_init\_\_
```python
def __init__(fname)
```
Opens a XISF file and extract its metadata. To get the metadata and the images, see get_file_metadata(),
get_images_metadata() and read_image().
**Arguments**:
- `fname` - filename
**Returns**:
XISF object.
<a id="xisf.XISF.get_images_metadata"></a>
#### get\_images\_metadata
```python
def get_images_metadata()
```
Provides the metadata of all image blocks contained in the XISF File, extracted from
the header (<Image> core elements). To get the actual image data, see read_image().
It outputs a dictionary m_i for each image, with the following structure:
```
m_i = {
'geometry': (width, height, channels), # only 2D images (with multiple channels) are supported
'location': (pos, size), # used internally in read_image()
'dtype': np.dtype('...'), # derived from sampleFormat argument
'compression': (codec, uncompressed_size, item_size), # optional
'key': 'value', # other <Image> attributes are simply copied
...,
'FITSKeywords': { <fits_keyword>: fits_keyword_values_list, ... },
'XISFProperties': { <xisf_property_name>: property_dict, ... }
}
where:
fits_keyword_values_list = [ {'value': <value>, 'comment': <comment> }, ...]
property_dict = {'id': <xisf_property_name>, 'type': <xisf_type>, 'value': property_value, ...}
```
**Returns**:
list [ m_0, m_1, ..., m_{n-1} ] where m_i is a dict as described above.
<a id="xisf.XISF.get_file_metadata"></a>
#### get\_file\_metadata
```python
def get_file_metadata()
```
Provides the metadata from the header of the XISF File (<Metadata> core elements).
**Returns**:
dictionary with one entry per property: { <xisf_property_name>: property_dict, ... }
where:
```
property_dict = {'id': <xisf_property_name>, 'type': <xisf_type>, 'value': property_value, ...}
```
<a id="xisf.XISF.get_metadata_xml"></a>
#### get\_metadata\_xml
```python
def get_metadata_xml()
```
Returns the complete XML header as a xml.etree.ElementTree.Element object.
**Returns**:
- `xml.etree.ElementTree.Element` - complete XML XISF header
<a id="xisf.XISF.read_image"></a>
#### read\_image
```python
def read_image(n=0, data_format='channels_last')
```
Extracts an image from a XISF object.
**Arguments**:
- `n` - index of the image to extract in the list returned by get_images_metadata()
- `data_format` - channels axis can be 'channels_first' or 'channels_last' (as used in
keras/tensorflow, pyplot's imshow, etc.), 0 by default.
**Returns**:
Numpy ndarray with the image data, in the requested format (channels_first or channels_last).
<a id="xisf.XISF.read"></a>
#### read
```python
@staticmethod
def read(fname, n=0, image_metadata={}, xisf_metadata={})
```
Convenience method for reading a file containing a single image.
**Arguments**:
- `fname` _string_ - filename
- `n` _int, optional_ - index of the image to extract (in the list returned by get_images_metadata()). Defaults to 0.
- `image_metadata` _dict, optional_ - dictionary that will be updated with the metadata of the image.
- `xisf_metadata` _dict, optional_ - dictionary that will be updated with the metadata of the file.
**Returns**:
- `[np.ndarray]` - Numpy ndarray with the image data, in the requested format (channels_first or channels_last).
<a id="xisf.XISF.write"></a>
#### write
```python
@staticmethod
def write(fname, im_data, creator_app=None, image_metadata={}, xisf_metadata={}, codec=None, shuffle=False, level=None)
```
Writes an image (numpy array) to a XISF file. Compression may be requested but it only
will be used if it actually reduces the data size.
**Arguments**:
- `fname` - filename (will overwrite if existing)
- `im_data` - numpy ndarray with the image data
- `creator_app` - string for XISF:CreatorApplication file property (defaults to python version in None provided)
- `image_metadata` - dict with the same structure described for m_i in get_images_metadata().
Only 'FITSKeywords' and 'XISFProperties' keys are actually written, the rest are derived from im_data.
- `xisf_metadata` - file metadata, dict with the same structure returned by get_file_metadata()
- `codec` - compression codec ('zlib', 'lz4', 'lz4hc' or 'zstd'), or None to disable compression
- `shuffle` - whether to apply byte-shuffling before compression (ignored if codec is None). Recommended
for 'lz4' ,'lz4hc' and 'zstd' compression algorithms.
- `level` - for zlib, 1..9 (default: 6); for lz4hc, 1..12 (default: 9); for zstd, 1..22 (default: 3).
Higher means more compression.
**Returns**:
- `bytes_written` - the total number of bytes written into the output file.
- `codec` - The codec actually used, i.e., None if compression did not reduce the data block size so
compression was not finally used.
Raw data
{
"_id": null,
"home_page": "",
"name": "xisf",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "astronomy,XISF",
"author": "",
"author_email": "Sergio D\u00edaz <sergio.diaz.ruiz@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/62/1d/eabf63b49878eeb3ef4ec8519c98f2cdbe3148e20d865dd8aff0e902f7e6/xisf-0.9.5.tar.gz",
"platform": null,
"description": "<a id=\"xisf\"></a>\r\n\r\n# xisf\r\n\r\nXISF Encoder/Decoder (see https://pixinsight.com/xisf/).\r\n\r\nThis implementation is not endorsed nor related with PixInsight development team.\r\n\r\nCopyright (C) 2021-2022 Sergio D\u00edaz, sergiodiaz.eu\r\n\r\nThis program is free software: you can redistribute it and/or modify it\r\nunder the terms of the GNU General Public License as published by the\r\nFree Software Foundation, version 3 of the License.\r\n\r\nThis program is distributed in the hope that it will be useful, but WITHOUT\r\nANY WARRANTY; without even the implied warranty of MERCHANTABILITY or\r\nFITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for\r\nmore details.\r\n\r\nYou should have received a copy of the GNU General Public License along with\r\nthis program. If not, see <http://www.gnu.org/licenses/>.\r\n\r\n<a id=\"xisf.XISF\"></a>\r\n\r\n## XISF Objects\r\n\r\n```python\r\nclass XISF()\r\n```\r\n\r\nImplements an baseline XISF Decoder and a simple baseline Encoder.\r\nIt parses metadata from Image and Metadata XISF core elements. Image data is returned as a numpy ndarray \r\n(using the \"channels-last\" convention by default). \r\n\r\nWhat's supported: \r\n- Monolithic XISF files only\r\n - XISF data blocks with attachment, inline or embedded block locations \r\n - Planar pixel storage models, *however it assumes 2D images only* (with multiple channels)\r\n - UInt8/16/32 and Float32/64 pixel sample formats\r\n - Grayscale and RGB color spaces \r\n- Decoding:\r\n - multiple Image core elements from a monolithic XISF file\r\n - Support all standard compression codecs defined in this specification for decompression \r\n (zlib/lz4[hc]/zstd + byte shuffling)\r\n- Encoding:\r\n - Single image core element with an attached data block\r\n - Support all standard compression codecs defined in this specification for decompression \r\n (zlib/lz4[hc]/zstd + byte shuffling)\r\n- \"Atomic\" properties (scalar types, String, TimePoint), Vector and Matrix (e.g. astrometric solutions)\r\n- Metadata and FITSKeyword core elements\r\n\r\nWhat's not supported (at least by now):\r\n- Read pixel data in the normal pixel storage models\r\n- Read pixel data in the planar pixel storage models other than 2D images\r\n- Complex and Table properties\r\n- Any other not explicitly supported core elements (Resolution, Thumbnail, ICCProfile, etc.)\r\n\r\nUsage example:\r\n```\r\nfrom xisf import XISF\r\nimport matplotlib.pyplot as plt\r\nxisf = XISF(\"file.xisf\")\r\nfile_meta = xisf.get_file_metadata() \r\nfile_meta\r\nims_meta = xisf.get_images_metadata()\r\nims_meta\r\nim_data = xisf.read_image(0)\r\nplt.imshow(im_data)\r\nplt.show()\r\nXISF.write(\r\n \"output.xisf\", im_data, \r\n creator_app=\"My script v1.0\", image_metadata=ims_meta[0], xisf_metadata=file_meta, \r\n codec='lz4hc', shuffle=True\r\n)\r\n```\r\n\r\nIf the file is not huge and it contains only an image (or you're interested just in one of the \r\nimages inside the file), there is a convenience method for reading the data and the metadata:\r\n```\r\nfrom xisf import XISF\r\nimport matplotlib.pyplot as plt \r\nim_data = XISF.read(\"file.xisf\")\r\nplt.imshow(im_data)\r\nplt.show()\r\n```\r\n\r\nThe XISF format specification is available at https://pixinsight.com/doc/docs/XISF-1.0-spec/XISF-1.0-spec.html\r\n\r\n<a id=\"xisf.XISF.__init__\"></a>\r\n\r\n#### \\_\\_init\\_\\_\r\n\r\n```python\r\ndef __init__(fname)\r\n```\r\n\r\nOpens a XISF file and extract its metadata. To get the metadata and the images, see get_file_metadata(),\r\nget_images_metadata() and read_image().\r\n\r\n**Arguments**:\r\n\r\n- `fname` - filename\r\n \r\n\r\n**Returns**:\r\n\r\n XISF object.\r\n\r\n<a id=\"xisf.XISF.get_images_metadata\"></a>\r\n\r\n#### get\\_images\\_metadata\r\n\r\n```python\r\ndef get_images_metadata()\r\n```\r\n\r\nProvides the metadata of all image blocks contained in the XISF File, extracted from\r\nthe header (<Image> core elements). To get the actual image data, see read_image().\r\n\r\nIt outputs a dictionary m_i for each image, with the following structure:\r\n\r\n```\r\nm_i = { \r\n 'geometry': (width, height, channels), # only 2D images (with multiple channels) are supported\r\n 'location': (pos, size), # used internally in read_image()\r\n 'dtype': np.dtype('...'), # derived from sampleFormat argument\r\n 'compression': (codec, uncompressed_size, item_size), # optional\r\n 'key': 'value', # other <Image> attributes are simply copied \r\n ..., \r\n 'FITSKeywords': { <fits_keyword>: fits_keyword_values_list, ... }, \r\n 'XISFProperties': { <xisf_property_name>: property_dict, ... }\r\n}\r\n\r\nwhere:\r\n\r\nfits_keyword_values_list = [ {'value': <value>, 'comment': <comment> }, ...]\r\nproperty_dict = {'id': <xisf_property_name>, 'type': <xisf_type>, 'value': property_value, ...}\r\n```\r\n\r\n**Returns**:\r\n\r\n list [ m_0, m_1, ..., m_{n-1} ] where m_i is a dict as described above.\r\n\r\n<a id=\"xisf.XISF.get_file_metadata\"></a>\r\n\r\n#### get\\_file\\_metadata\r\n\r\n```python\r\ndef get_file_metadata()\r\n```\r\n\r\nProvides the metadata from the header of the XISF File (<Metadata> core elements).\r\n\r\n**Returns**:\r\n\r\n dictionary with one entry per property: { <xisf_property_name>: property_dict, ... }\r\n where:\r\n ```\r\n property_dict = {'id': <xisf_property_name>, 'type': <xisf_type>, 'value': property_value, ...}\r\n ```\r\n\r\n<a id=\"xisf.XISF.get_metadata_xml\"></a>\r\n\r\n#### get\\_metadata\\_xml\r\n\r\n```python\r\ndef get_metadata_xml()\r\n```\r\n\r\nReturns the complete XML header as a xml.etree.ElementTree.Element object.\r\n\r\n**Returns**:\r\n\r\n- `xml.etree.ElementTree.Element` - complete XML XISF header\r\n\r\n<a id=\"xisf.XISF.read_image\"></a>\r\n\r\n#### read\\_image\r\n\r\n```python\r\ndef read_image(n=0, data_format='channels_last')\r\n```\r\n\r\nExtracts an image from a XISF object.\r\n\r\n**Arguments**:\r\n\r\n- `n` - index of the image to extract in the list returned by get_images_metadata()\r\n- `data_format` - channels axis can be 'channels_first' or 'channels_last' (as used in\r\n keras/tensorflow, pyplot's imshow, etc.), 0 by default.\r\n \r\n\r\n**Returns**:\r\n\r\n Numpy ndarray with the image data, in the requested format (channels_first or channels_last).\r\n\r\n<a id=\"xisf.XISF.read\"></a>\r\n\r\n#### read\r\n\r\n```python\r\n@staticmethod\r\ndef read(fname, n=0, image_metadata={}, xisf_metadata={})\r\n```\r\n\r\nConvenience method for reading a file containing a single image.\r\n\r\n**Arguments**:\r\n\r\n- `fname` _string_ - filename\r\n- `n` _int, optional_ - index of the image to extract (in the list returned by get_images_metadata()). Defaults to 0.\r\n- `image_metadata` _dict, optional_ - dictionary that will be updated with the metadata of the image.\r\n- `xisf_metadata` _dict, optional_ - dictionary that will be updated with the metadata of the file.\r\n \r\n\r\n**Returns**:\r\n\r\n- `[np.ndarray]` - Numpy ndarray with the image data, in the requested format (channels_first or channels_last).\r\n\r\n<a id=\"xisf.XISF.write\"></a>\r\n\r\n#### write\r\n\r\n```python\r\n@staticmethod\r\ndef write(fname, im_data, creator_app=None, image_metadata={}, xisf_metadata={}, codec=None, shuffle=False, level=None)\r\n```\r\n\r\nWrites an image (numpy array) to a XISF file. Compression may be requested but it only\r\nwill be used if it actually reduces the data size.\r\n\r\n**Arguments**:\r\n\r\n- `fname` - filename (will overwrite if existing)\r\n- `im_data` - numpy ndarray with the image data\r\n- `creator_app` - string for XISF:CreatorApplication file property (defaults to python version in None provided)\r\n- `image_metadata` - dict with the same structure described for m_i in get_images_metadata().\r\n Only 'FITSKeywords' and 'XISFProperties' keys are actually written, the rest are derived from im_data.\r\n- `xisf_metadata` - file metadata, dict with the same structure returned by get_file_metadata()\r\n- `codec` - compression codec ('zlib', 'lz4', 'lz4hc' or 'zstd'), or None to disable compression\r\n- `shuffle` - whether to apply byte-shuffling before compression (ignored if codec is None). Recommended\r\n for 'lz4' ,'lz4hc' and 'zstd' compression algorithms.\r\n- `level` - for zlib, 1..9 (default: 6); for lz4hc, 1..12 (default: 9); for zstd, 1..22 (default: 3).\r\n Higher means more compression.\r\n\r\n**Returns**:\r\n\r\n- `bytes_written` - the total number of bytes written into the output file.\r\n- `codec` - The codec actually used, i.e., None if compression did not reduce the data block size so\r\n compression was not finally used.\r\n\r\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 (GPLv3)",
"summary": "Encoder/Decoder for XISF (Extensible Image Serialization Format)",
"version": "0.9.5",
"project_urls": {
"Homepage": "https://github.com/sergio-dr/xisf"
},
"split_keywords": [
"astronomy",
"xisf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cda7be5345f9000558a3c905be3526043cd68471ab5243cdf9ca1b84f760dc7b",
"md5": "69c78e61090849c0522ceb6ff65e32a2",
"sha256": "c04d92048ecf04b57e24cdf04360c35c1b712e4ba5014e57e16fb7ebd94ae15d"
},
"downloads": -1,
"filename": "xisf-0.9.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "69c78e61090849c0522ceb6ff65e32a2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 27131,
"upload_time": "2024-03-02T11:26:49",
"upload_time_iso_8601": "2024-03-02T11:26:49.544242Z",
"url": "https://files.pythonhosted.org/packages/cd/a7/be5345f9000558a3c905be3526043cd68471ab5243cdf9ca1b84f760dc7b/xisf-0.9.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "621deabf63b49878eeb3ef4ec8519c98f2cdbe3148e20d865dd8aff0e902f7e6",
"md5": "1791b85009ad6ce73c625794ef8c547a",
"sha256": "14c19cf90060d38bb8f299f00ec903eef17e9a75709fb6308e12f6349b989b68"
},
"downloads": -1,
"filename": "xisf-0.9.5.tar.gz",
"has_sig": false,
"md5_digest": "1791b85009ad6ce73c625794ef8c547a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 30166,
"upload_time": "2024-03-02T11:26:51",
"upload_time_iso_8601": "2024-03-02T11:26:51.393258Z",
"url": "https://files.pythonhosted.org/packages/62/1d/eabf63b49878eeb3ef4ec8519c98f2cdbe3148e20d865dd8aff0e902f7e6/xisf-0.9.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-02 11:26:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sergio-dr",
"github_project": "xisf",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "xisf"
}
