github ↗
docs menu

Module Ymir.Grid

Cells seen through a transform.

A cell is one sample's footprint, a pixel's square. A pixel grid is a shape and a transform from its pixel coordinates to its world, 'w: directions on the sky or points in a plane. Cell (i, j) has its centre at pixel coordinates (i, j), 0-based in the data tensor's axis order, and its corners at (i ± ½, j ± ½).

A window is a block of a grid's cells of static shape at a traced start, [...; 2], possibly batched: the grid of a stamp, or of a million stamps. A window keeps its base, the whole image's shape, and its transform over the whole image's pixel coordinates, so its cells are the base's cells. Cells beyond the base exist in a window, mapped through the same transform. The border of a window is its outer ring of cells.

A cell's measure is its solid angle on the sky, or its area in a plane: the measure of the quadrilateral of its corners mapped to the world the grid was built with, with great-circle edges on the sky. Grid.map_world changes the world and keeps the measures. Measures are computed in float64.

#type ('w, 'e, 'd) t

The type for grids of cells whose world is 'w, with measures at dtype 'e.

#val cell : Unit.t

cell is the unscoped symbol counting cells. Data per cell carry cell⁻¹: electrons per second in a cell are Unit.(symbol "electron" / second / Grid.cell). It never converts to an angle; the grid's measure does that. A file's per-pixel unit, such as FITS's pix⁻¹, is cell⁻¹ when the grid is that file's; the program states it.

#val pixels : at:'d Nx.Placement.t -> shape:int array -> (float, 'e) Nx.dtype -> ('d Transform.plane, 'w, 'd) Transform.t -> ('w, 'e, 'd) t

pixels ~at ~shape dtype t is the image of shape cells, [|rows; columns|], seen through t: the whole image, its own base, with measures at dtype and its window's start at at.

Raises Invalid_argument unless shape is two non-negative sizes.

#type ('w, 'e, 'd) kind =
  1. #| Pixels : {
    1. #base : int array;
      (*

      The whole image's shape.

      *)
    2. #shape : int array;
      (*

      The window's shape.

      *)
    3. #start : 'd Nx.int64_t;
      (*

      The window's first cell, [...; 2].

      *)
    4. #transform : ('d Transform.plane, 'w, 'd) Transform.t;
      (*

      From the whole image's pixel coordinates.

      *)
    } -> ('w, 'e, 'd) kind

The type for a grid's kind.

#val kind : ('w, 'e, 'd) t -> ('w, 'e, 'd) kind

kind g is g's kind and parts.

#val shape : ('w, 'e, 'd) t -> int array

shape g is the shape of g's cells: the data's last axes.

#val centres : ('w, 'e, 'd) t -> 'w

centres g is each cell's centre in the world, batch @ shape g points. A window's centres are its base's at the same cells, bit for bit.

Raises Invalid_argument as Transform.apply does.

#val corners : ('w, 'e, 'd) t -> 'w

corners g is each cell's four corners in the world, batch @ shape g @ [4] points, counter-clockwise in the pixel plane.

#val measure : ('w, 'e, 'd) t -> (float, 'e, 'd) Nx.t Quantity.t

measure g is each cell's measure, batch @ shape g: in steradians on the sky, by Van Oosterom and Strackee's formula on corner differences, within about 1e-9 of a 0.031″ TAN pixel's solid angle; in the plane's unit squared in a plane, by the shoelace formula.

#val map_world : ('w, 'v, 'd) Transform.t -> ('w, 'e, 'd) t -> ('v, 'e, 'd) t

map_world t g is g's cells seen in the world t maps g's world to: its transform followed by t. Its cells and their measures are g's, taken in the world g was built with.

#val agree : ('w, 'e, 'd) t -> ('w, 'e, 'd) t -> 'd Nx.bool_t

agree a b is where a and b are the same cells in the same world: false if their kinds, shapes, stages, codes, frames or units differ, and otherwise whether every parameter holds the same numbers, NaN equal to NaN, one boolean per batch element. It does not raise. Agreement is exact: two headers that differ in their last digit give grids that do not agree.

#val window : start:'d Nx.int64_t -> shape:int array -> ('w, 'e, 'd) t -> ('w, 'e, 'd) t

window ~start ~shape g is the block of shape cells of g from start, [...; 2] along g's own axes. Its batch axes are start's.

Raises Invalid_argument unless shape is two non-negative sizes and start's last axis is 2.

#val around : 'w -> shape:int array -> ('w, 'e, 'd) t -> ('w, 'e, 'd) t

around x ~shape g is the shape block of g's base centred on the cell holding each point x, located through the inverse transform, with the extra cell of an even size on the high side. Its batch axes are x's. It carries no derivative and does not raise at any point: a point the inverse does not cover gets a window wholly beyond the base, and every start is clamped to [-shape, base].

Raises Invalid_argument unless shape is two non-negative sizes.

#val ptree : unit -> (('w, 'e, 'd) t, 'd) Nx.Ptree.t

ptree () is the structure of grids: the kind, the base and window shapes and the dtype as static data, then the start and the transform.