Skip to content

NGFF transformations basic functions

Jump to bottom
bogovicj edited this page Jun 14, 2022 · 5 revisions

A set of functions that can describe transformations in the ome-ngff spec.

Note: these functions are intended to serve as a good implementation of the specification,but rather to describe its functionality

coordinate systems and points

A coordinate system is an ordered list of named axes. An axis MUST have a name, but MAY have other properties (e.g. type, unit). In this document, a coordinate system (cs) will be a list of strings, for example:

cs = [ "x", "f(Hz)", "saltiness" ]

cs is a three-dimensional coordinate system.

Points may be described in two different, but related ways. As lists (1d arrays) of coordinates, or as maps (dictionaries) from axis names to coordinates. Points can be converted from one representation to another, given a coordinate system. In this document, the elements of the list and the values of the map MUST be numeric, but this can be generalized.

general transformations

A transformation is a function whose input is an list of dimension N and whose output is a list of dimension M.

out[M] = f( in[N] )

representation conversion

point_list_to_map

point_list_to_map is a function whose inputs are a list and a coordinate system, and whose output is the map representation of that point in the given coordinate system.

example 1 
poist_list_to_map( [1, 2, 3], ['x', 'y', 'z'])

returns

{x:1, y:2, z:3}
example 2 

point_list_to_map( [1, 2, 3], ['z', 'x', 'y'])

returns

{z:1, x:2, y:3}

point_map_to_list

point_map_to_list is a function whose inputs are a map and a coordinate system, and whose output is the list representation of that point in the given coordinate system.

example 1 
point_map_to_list( {x:1, y:2, z:3}, ['x', 'y', 'z'])

returns

[1, 2, 3],
example 2 
point_map_to_list( {x:1, y:2, z:3}, ['z', 'x', 'y'])

returns

[3, 1, 2],

basic functions

map_by_index

A function whose inputs is a list, and whose output is the same list. my_by_index is the identity function for lists.

example 1 
map_by_index( [1, 2, 3] )

returns

[1, 2]

addToRight

addToRight takes two maps and returns a map. It's output keys are the union of the keys of both maps. If the key appears in both maps, the value in the resulting map is the value for the map that is the second input argument. For other keys, the value of the output map is the value of the key for the input map in which that key appears.

map_out = addToRight( map_left, map_right )
example 1 
addToRight( {a:1, b:2}, {c:3, d:4})

returns

{a:1, b:2, c:3, d:4}
example 2 
addToRight( {a:1, b:2}, {c:3, b:4})

returns

{a:1, b:4, c:3}

applyMap

Suppose a coordinate transformation's input, output, inputAxes, and outputAxes are accessible as fields of a t object. Assume also that it has an apply method with one argument - a list.

apply is a function that takes a coordinate transformation t, a point represented as a map m, It returns a list

m_out = applyMap( t, m )

it's easy to write down apply using the above functions:

applyMap( t, m )
    p_in = point_map_to_list( m, t.inputAxes )
    p_out = t.apply( p_in )
    m_tformed = point_list_to_map( p_out, t.outputAxes )
    return addToRight( m, m_tformed )

applySequence

applySequence is a function that takes a list of coordinate transformations, and a point represented as a map. It returns a point represented as a map that is the result of applying all the transformations in the list, in order, taking into acount their input and output axes. applyMap makes it easy to write down applySequence:

applySequence( tforms[], m )
    for t in tforms
        m = applyMap( t, m )

    return m

Properties

Given a coordinate system A, call point_list_to_map(l,A) R_A, and call point_map_to_list(m,A) R_A_inv (think "R"epresentation conversion). Given a list l, l = R_A_inv(R_A(l)), provided that the coordinate system has as many axes as the list's length. Given a map m, m = R_A(R_A_inv(m)), provided that every key in m is in A, and every axis in A is a key in m. So R_A and R_A_inv are inverses under appropriate conditions.

relating to the spec

Assume that the implementations of transformations operate on lists.

{
    "coordinateSystems" : [
        { "name": "ijk", "axes" : [ "i", "j", "k" ]},
        { "name": "xyz", "axes" : [ "x", "y", "z" ]}
    ],
    "coordinateTransformations" : [
        {
            "type" : "sequence",
            "input" : "ijk",
            "output" : "xyz",
            "transformations" : [
            { "name" : "f" "inputAxes" : ["i", "k"], "outputAxes" : ["x", "y"] }, 
            { "name" : "g" "inputAxes" : ["j"], "outputAxes" : ["z"] } 
        ]
        } 
    ],
}

In the example above, suppose the coordinate transformation f is implemented such that it takes one argument: a list of length 2, and has one output: a list of length 2. Similarly the coordinate transformation g is implemented such that it takes one argument: a list of length 1, and has one output: a list of length 1.

out_list_2 = f( in_list_2 )
out_list_1 = g( in_list_1 )

The set of inputAxes and outputAxes define "intermediate" coordinate systems, we'll call them "ik", "j", "xy", and "z" respectively. As above, say R_ik converts a point represented as a list to a map representation for coordinate system ik.

Notes

Add a map from axis name to axis name that can implement permutations, like:

{ "type" : "map", "map" : { "x" : "i", "y":"j", "z":"k" } }

Clone this wiki locally