GONet File Model

Core data structures for loaded GONet images and package-level file utilities.

GONet Package

Core GONet data structures, parsers, and utilities.

The gonet package provides the foundational classes and helper functions used throughout the GONet data processing ecosystem. It defines the object model for handling calibrated and raw camera data, along with tools for reading, writing, and analyzing GONet image files.

This package forms the backbone of the GONet data model. It unifies low-level binary parsing, high-level metadata management, and export routines into a single, object-oriented framework designed for robustness, extensibility, and scientific reproducibility.

Submodules

• gonet_file — Core GONetFile class for processed GONet images.

• gonet_file_raw — Specialized GONetFileRaw class for raw Bayer data.

• filetypes — Enumeration of GONet file types (e.g., SCIENCE, FLAT, DARK).

• config — Constants describing the GONet camera sensor geometry.

• io_utils — Low-level I/O utilities for scaling and range conversions.

• parsers — File readers for TIFF, RAW .jpg, and EXIF metadata.

• writers — Output utilities for exporting GONet data to TIFF, JPEG, and FITS.

• analysis_utils — Image preprocessing and calibration tools.

GONetFile

This module defines the GONetFile class, which provides functionality for handling and processing GONet files. The class encapsulates the properties and methods required for manipulating the image data (including blue, green, and red channels) and metadata associated with GONet files.

The module supports various operations on GONet files, including:

• Loading image data from original raw (.jpg) or TIFF formats.

• Performing arithmetic operations between GONet files and scalar values.

• Writing image data to common formats like JPEG, TIFF, and FITS.

• Parsing and handling metadata for different file types.

The GONetFile class also includes support for operator overloading, allowing users to easily perform element-wise operations between GONet files or between a GONet file and scalar values.

In order to ensure that all arithmetic operations on the image channels are safe and reliable, we cast the blue, green, and red channel arrays to float64 upon initialization. The original pixel data is typically stored as uint12 or uint16, which are prone to overflow or precision loss during common operations like addition, subtraction, or division. By promoting the arrays to float64, we avoid these issues and enable robust numerical processing — particularly important for calibration, normalization, or stacked image analysis. This casting ensures consistency and protects users from subtle bugs that can arise from working with fixed-width integer types.

From the GONetFile, GONetFileRaw class is derived, which keeps the 2 green channels separate and has basic functionality to work in the raw Bayer-plane format.

Classes

• GONetFile: A class representing a GONet file.

Example usage

gonet_file = GONetFile.from_file('example_image.tiff')
plt.imshow(gonet_file.green)

class GONet_Wizard.GONet_utils.src.gonet.gonet_file.GONetFile(filename, blue, green, red, meta, filetype)

Bases: object

In-memory representation of a processed three-channel GONet image.

A GONetFile stores blue, green, and red image channels together with parsed metadata and a FileType. The constructor accepts already-loaded arrays; most users should create instances with from_file(), which dispatches to the appropriate parser for supported GONet file formats.

Channel arrays are converted to float64 during initialization so that arithmetic, dark/overscan correction, normalization, and stacking operations do not silently overflow fixed-width integer image data.

CHANNELS

Canonical processed-channel names: ["blue", "green", "red"].

Type:

list of str

COLORS

Default plotting colors keyed by channel name.

Type:

dict

Notes

Arithmetic operators act channel-by-channel and return new image objects. Operations between two GONetFile instances require matching channel shapes.

property filename: str

Get the filename of the GONet file.

Returns:

str – The name or path of the file associated with this GONetFile instance.

property blue: ndarray

Get the blue channel data from the GONet file.

Returns:

numpy.ndarray – A 2D array of pixel values corresponding to the blue channel.

property green: ndarray

Get the green channel data from the GONet file.

Returns:

numpy.ndarray – A 2D array of pixel values corresponding to the green channel.

property red: ndarray

Get the red channel data from the GONet file.

Returns:

numpy.ndarray – A 2D array of pixel values corresponding to the red channel.

property meta: dict

Get the metadata associated with the GONet file.

Returns:

dict – Dictionary containing metadata fields extracted from the file header or sidecar.

property filetype: FileType

Get the file type of the GONet file.

Returns:

FileType – The type of the file, such as SCIENCE, FLAT, etc.

get_channel(channel_name)

Retrieve the pixel data for a specified color channel.

This method returns the image data associated with the specified color channel as a numpy.ndarray.

Parameters:

channel_name (ChannelName) – The name of the channel to retrieve. Must be one of 'blue', 'green', or 'red'.

Return type:

ndarray

Returns:

numpy.ndarray – The pixel data corresponding to the requested color channel.

Raises:

ValueError – If an invalid channel name is provided.

set_channel(channel_name, data, check_shape=True)

Set the pixel data for a specified color channel.

This method updates the image data associated with the specified color channel.

Parameters:

• channel_name (ChannelName) – The name of the channel to update. Must be one of 'blue', 'green', or 'red'.

• data (numpy.ndarray) – A 2D array of pixel values to assign to the specified channel. The shape of the array must match the current channel dimensions.

• check_shape (bool, optional) – If True (default), the method checks that the shape of data matches the existing channel shape before assignment. If False, no shape check is performed.

Raises:

ValueError – If an invalid channel name is provided or if the shape of the input data does not match the current channel dimensions.

Return type:

None

remove_overscan(*args, **kwargs)

Remove overscan regions from the image data.

See remove_overscan() for full documentation.

write_to_jpeg(*args, **kwargs)

Write the RGB image data to a JPEG file.

See write_to_jpeg() for full documentation.

write_to_tiff(*args, **kwargs)

Write the image data to a multi-page TIFF file.

See write_to_tiff() for full documentation.

write_to_fits(*args, **kwargs)

Write the image data to a FITS file.

See write_to_fits() for full documentation.

classmethod from_file(filepath, filetype=FileType.SCIENCE, meta=True)

Create a GONetFile instance from a TIFF or JPEG file.

This class method reads a GONet image file, extracts the blue, green, and red channel data, and optionally parses the associated metadata. It returns a fully initialized GONetFile object.

Parameters:

• filepath (str or pathlib.Path) – Full path to the image file. The file must be in .tif, .tiff, or .jpg format.

• filetype (FileType, optional) – Type of the file, chosen from the FileType enumeration. Defaults to FileType.SCIENCE.

• meta (bool, optional) – If True (default), metadata will be extracted and included. If False, metadata will be skipped.

Return type:

GONetFile

Returns:

GONetFile – A new instance initialized with the file’s pixel data and metadata.

Raises:

• FileNotFoundError – If the specified file does not exist.

• ValueError – If the file extension is unsupported (must be .tif, .tiff, .jpg).

Notes

Metadata extraction is supported only for .jpg files. TIFF files are read for image data only.

GONetFileRaw

Specialized handling of RAW GONet .jpg images containing BGGR Bayer data.

This module defines the GONetFileRaw class, a subclass of GONetFile designed for working with unprocessed RAW GONet camera files. Unlike the base class, which stores a single averaged green channel, this subclass preserves both green channels present in the BGGR Bayer mosaic (green1 and green2).

The GONetFileRaw class provides tools for reading RAW .jpg files, handling per-channel arithmetic operations, converting between compact (H, W) quads and full (2H, 2W) Bayer-plane representations, and maintaining consistent metadata and file typing with the base GONetFile.

Classes

• GONetFileRaw: A class representing a RAW GONet file with separate green channels.

class GONet_Wizard.GONet_utils.src.gonet.gonet_file_raw.GONetFileRaw(filename, blue, green1, green2, red, meta, filetype, is_bayer_planes=False)

Bases: GONetFile

In-memory representation of RAW GONet data with separate Bayer channels.

RAW GONet images use a BGGR mosaic with two distinct green samples. This subclass preserves those samples as green1 and green2 instead of immediately averaging them into the processed green channel used by GONetFile.

Instances may be stored in either compact quad representation (H, W) or expanded Bayer-plane representation (2H, 2W). The is_bayer_planes flag records which representation is currently in use, and conversion helpers move between the two forms.

CHANNELS

Raw channel names: ["blue", "green1", "green2", "red"].

Type:

list of str

COLORS

Default plotting colors keyed by raw channel name.

Type:

dict

property green1: ndarray

Get the first green channel.

Returns:

numpy.ndarray – 2D array representing the first green channel.

property green2: ndarray

Get the second green channel.

Returns:

numpy.ndarray – 2D array representing the second green channel.

property green: ndarray

Override the green property to prevent access. Accessing a single combined green channel is invalid for GONetFileRaw.

Raises:

AttributeError – Always raised, because GONetFileRaw maintains separate green1 and green2 channels and does not define a combined green channel.

property is_bayer_planes: bool

True if channel arrays are expanded to (2H, 2W) Bayer-plane coordinates.

Returns:

bool – Indicates if the channel arrays represent Bayer planes.

classmethod from_file(filepath, filetype=FileType.SCIENCE, meta=True)

Load a GONetFileRaw instance from a RAW .jpg file.

Parameters:

• filepath (Union[str, Path]) – The path to the .jpg file.

• filetype (FileType, optional) – The type of the file (default is FileType.SCIENCE).

• meta (bool, optional) – Whether to parse metadata from the file (default is True).

Return type:

GONetFileRaw

Returns:

GONetFileRaw – The loaded GONetFileRaw instance.

to_bayer_planes(fill_value=nan)

Expand per-channel images to Bayer-sized planes with values only at the pixel locations of each channel in the CFA pattern; other pixels are filled.

Parameters:

fill_value (float or int, optional) – Value to place where a given channel does not live (default: NaN).

Return type:

dict[str, ndarray]

Returns:

dict of numpy.ndarray – Dictionary with keys ‘red’, ‘green1’, ‘green2’, ‘blue’, each of shape (2H, 2W).

Raises:

ValueError – If the CFA pattern is unsupported or channel shapes are inconsistent.

as_bayer_planes(inplace=True, fill_value=nan)

Return a new GONetFileRaw whose channels are Bayer-sized (2H, 2W) planes.

Parameters:

• inplace (bool, optional) – If True, modifies the current instance in-place. If False, returns a new instance with Bayer-plane channels.

• fill_value (float or int, optional) – Value to place where a given channel does not live (default: NaN).

Return type:

GONetFileRaw

Returns:

GONetFileRaw – A new instance with channels expanded to Bayer-plane coordinates.

as_compact_quads()

Return a new GONetFileRaw whose channels are compact (H, W) quads, by sampling each channel at its CFA parity from Bayer planes.

Return type:

GONetFileRaw

Returns:

GONetFileRaw – A new instance with channels in compact (H, W) per-channel form.

Configuration

Configuration constants defining the raw GONet camera specifications.

This module contains the fundamental constants describing the GONet camera’s sensor geometry and data layout. These parameters are used throughout the GONet processing pipeline for decoding, reading, and reshaping the binary image data stored in RAW .jpg files.

Constants

RAW_FILE_OFFSETint

Offset in bytes to the beginning of the raw data.

RAW_HEADER_SIZEint

Size in bytes of the file header preceding the image data.

RAW_DATA_OFFSETint

Effective offset to the start of image data, computed as RAW_FILE_OFFSET - RAW_HEADER_SIZE.

RELATIVETOENDint

File-seek flag indicating offset is relative to file end.

PIXEL_PER_LINEint

Number of pixels per image row on the sensor.

PIXEL_PER_COLUMNint

Number of pixels per image column on the sensor.

PADDED_LINE_BYTESint

Number of bytes used to store each image row including padding.

USED_LINE_BYTESint

Number of bytes actually containing pixel data (for 12-bit encoding, PIXEL_PER_LINE * 12 / 8).

ChannelNametyping.Literal

Type hint for channel names (raw or processed).

CHANNEL_NAMES_RAWtuple of str

Ordered tuple of RAW channel names: (‘blue’, ‘green1’, ‘green2’, ‘red’).

CHANNEL_NAMES_PROCESSEDtuple of str

Ordered tuple of processed channel names: (‘blue’, ‘green’, ‘red’).

Functions

get_channel_bayer_offsetscallable

Returns the (row, col) offsets for a given channel in the BGGR Bayer pattern.

GONet_Wizard.GONet_utils.src.gonet.config.get_channel_bayer_offsets(channel)

Get the row and column byte offsets for a channel in the BGGR Bayer pattern.

Parameters:

channel (ChannelName) – One of ‘blue’, ‘green1’, ‘green2’, or ‘red’.

Return type:

tuple[int, int]

Returns:

tuple of int – (row_offset, col_offset) indicating the starting pixel location for the channel in the Bayer mosaic.

Raises:

ValueError – If the channel name is not recognized.

File Types

Definition of standard file type categories used in GONet observations.

This module provides the FileType enumeration, which defines the standard types of frames produced by GONet cameras. These file type labels are used throughout the GONet processing pipeline to identify the purpose of each file—whether it represents science data, calibration frames, or instrumental corrections.

Classes

• FileType : Enumeration of file types used in GONet observations (e.g., science, flat, bias, dark).

class GONet_Wizard.GONet_utils.src.gonet.filetypes.FileType(value)

Bases: Enum

Enumeration of file types used in GONet observations.

This enum defines the standard types of data that a GONet file may represent, used for categorizing the file during processing or analysis.

SCIENCE

Represents a science frame (standard observational data).

Type:

FileType

FLAT

Represents a flat field frame (used for pixel response correction).

Type:

FileType

BIAS

Represents a bias frame (used for sensor readout offset correction).

Type:

FileType

DARK

Represents a dark frame (used to correct for dark current noise).

Type:

FileType

I/O Utilities

Utility functions for low-level I/O and numeric data transformations used by GONet files.

This module contains helper routines that perform standard numeric conversions and data handling for GONet raw files and related image-processing workflows.

The functions defined here are intended to be lightweight and dependency-free, providing basic data scaling and consistency utilities used throughout the GONet_Wizard.GONet_utils package.

Functions

• scale_uint12_to_16bit_range()

  Linearly scale 12-bit unsigned integer values to the full 16-bit range [0, 65535].

GONet_Wizard.GONet_utils.src.gonet.io_utils.scale_uint12_to_16bit_range(x)

Linearly scales unsigned 12-bit integer values to the full 16-bit range [0, 65535].

This function maps values from the uint12 range [0, 4095] to the float range [0, 65535], preserving relative magnitudes without rounding or type conversion to integer.

Parameters:

x (array-like or int) – Input value(s) in the uint12 range [0, 4095]. Can be a scalar or NumPy array.

Returns:

np.ndarray or float – Scaled value(s) in the float range [0.0, 65535.0]. Output dtype is float64.

Raises:

ValueError – If any input values are outside the valid uint12 range.