docs menu

Module Fits.Image

Images.

Elements. BITPIX gives the stored format; when BSCALE is 1 and BZERO is the standard's offset for it (Table 11), the format is unsigned, or signed for bytes. BSCALE and BZERO compare as exact decimals: 32768, 3.2768E4 and 32768.0 are one offset. Any other BSCALE or BZERO makes the image scaled: its element is BITPIX's own format.

Values. Image.raw returns stored numbers in any dtype that holds every value of the element exactly; Image.values returns physical values in a float dtype. On a scaled image the physical value of a stored s is BZERO + BSCALE × s computed as Nx.fma bscale s bzero in float64, BSCALE and BZERO the float64s nearest their text, then cast to the dtype once.

Undefined pixels. BLANK names a stored value of an integer BITPIX, and NaN is undefined in a float image. Image.values returns NaN there and Image.raw the stored number.

Windows. window is a (start, stop) range per axis, in the tensor's axis order, as Nx.slice takes R (start, stop). A read copies only the rows the window covers. A window of the wrong rank or past the shape is an Error; a range with start < 0 or start > stop raises Invalid_argument.

Tiles. A tile-compressed image, a BINTABLE of ZIMAGE = T, reads as the image it holds, and a read decodes only the tiles its window meets.

Memory. A read allocates its window, and decodes the tiles it meets one at a time: a Rice, gzip or uncompressed tile whole, in memory for its pixels, which its heap bytes bound, and a PLIO or HCOMPRESS tile only where it meets the window, in memory for its stream and that part. A few bytes of a PLIO or HCOMPRESS tile stand for any number of pixels, so the file's size bounds neither the image nor such a tile: a whole read allocates the declared Image.shape, which a caller checks before reading an untrusted image whole.

Byte order. FITS stores big-endian. Every result is host memory independent of the file.

#type t

The type for an image's description: shape, stored format, scaling and BLANK.

#val of_hdu : hdu -> (t, string) Stdlib.result

of_hdu hdu describes a primary array or an IMAGE extension. It is an Error for other kinds, for random groups, for NAXIS = 0 and for more than 32 axes.

#val shape : t -> int array

shape t is [|NAXISn; …; NAXIS1|].

#val element : t -> Nx.Dtype.any

element t is the stored format, the standard's unsigned offsets included.

#val scaled : t -> bool

scaled t is true iff BSCALE or BZERO scale the stored numbers beyond the offsets.

#val pp : Stdlib.Format.formatter -> t -> unit

pp formats the element and shape, as float32 [4800; 4600], and the scaling and BLANK.

val raw : 
  ?window:(int * int) array ->
  ('a, 'b) Nx.dtype ->
  hdu ->
  (('a, 'b, Nx.host) Nx.t, string) Stdlib.result

raw ~window dtype hdu is the stored numbers of hdu's image as dtype. It is an Error naming the dtypes that hold the element if dtype does not hold every value of it exactly.

val values : 
  ?window:(int * int) array ->
  (float, 'b) Nx.dtype ->
  hdu ->
  ((float, 'b, Nx.host) Nx.t, string) Stdlib.result

values ~window dtype hdu is the physical values of hdu's image, NaN where undefined. On an unscaled image it succeeds exactly when raw does.

val validity : 
  ?window:(int * int) array ->
  hdu ->
  (Nx.host Nx.bit_t option, string) Stdlib.result

validity ~window hdu is false where a pixel is undefined (BLANK or NaN), or None if none is.

#val hdu : ?tiles:int array -> Header.t -> ('a, 'b, Nx.host) Nx.t -> hdu

hdu ~tiles h t is t as an image HDU with h's cards that are not structural (write); BLANK is dropped from a float image. With tiles, a tile shape in tensor axis order, it is tile-compressed: Rice-coded for integers and GZIP_2 for floats. It reads back bit for bit, NaN payloads included. Tiles of int64 and uint64 are refused: cfitsio, which funpack and most FITS readers use, decompresses no 64-bit integer tiles.

Raises Invalid_argument if t is a scalar or of a dtype FITS images do not hold (bool, bit, complex, float16, bfloat16, the float8s, int4, uint4), naming the cast that stores it, if tiles is not of t's rank with positive sizes, or if t is int64 or uint64 with tiles.

val quantized : 
  ?tiles:int array ->
  float ->
  Header.t ->
  (float, 'b, Nx.host) Nx.t ->
  hdu

quantized ~tiles q h t stores t Rice-coded in integer steps of each tile's noise divided by q, in tiles of one row unless tiles, dithered by SUBTRACTIVE_DITHER_2, which keeps zeros exact; NaN pixels are undefined. The noise estimate, quantizer and rounding are cfitsio's, and the dither seed is computed from the pixels, so equal images give equal bytes. A tile with no noise or a range past int32 is stored losslessly.

Raises Invalid_argument if q is not positive and finite, if t is not float32 or float64, or as hdu does.