Document if and how image dimensions are flipped when sent to another process

[tinevez]

For instance on Java side:

Wrapping an ImagePlus into an imglib2 ImgPlus gives you an image which can be XYCT.

Wrapping this ImgPlus into an NDArray will make this data appears as TCYX on the Python side.

This is actually the desirable order in Python. We should just document this explicitly.

[ctrueden]

See also imagej/pyimagej#151.

[ctrueden]

I find the following Python functions handy when going between Java and Python:

def flip_img(img):
    """Flips a NumPy array between Java/ImgLib2 (F_ORDER) and NumPy-friendly (C_ORDER)"""
    return np.transpose(img, tuple(reversed(range(img.ndim))))

def share_as_ndarray(img):
    """Copies a NumPy array into a same-sized newly allocated block of shared memory"""
    from appose import NDArray
    shared = NDArray(str(img.dtype), img.shape)
    shared.ndarray()[:] = img
    return shared

When receiving an appose.NDArray input named appose_ndarray from Java in your Python script:

numpy_ndarray = flip_img(appose_ndarray)

When outputting a NumPy array named mask_nuclei to Java via a task.outputs entry:

task.outputs["nuclei"] = share_as_ndarray(flip_img(mask_nuclei))

I hope to make this less boilerplatey in the future—it would be great to just pass numpy arrays and ImgLib2 images directly as inputs/outputs, in which case the flipping could be done automatically—but for now, this is where we are.

P.S. Don't forget to close() your NDArray on the Java side, to avoid memory leaks~!

[ctrueden]

So, as pointed out by @tinevez, it turns out Appose is already doing the shape flipping: there is no need for the flip_img function above.

Here is a long-winded discussion of Appose's shape conventions and behavior.

Given shape (d₀, d₁) and element at index [i₀, i₁]:

Order	Flat index formula	Fastest-moving index	Memory term
C order	i₀·d₁ + i₁	last (i₁)	row-major
F order	i₁·d₀ + i₀	first (i₀)	column-major

C = row-major = last index fastest. F = column-major = first index fastest. Your

Concrete image example

W=3 columns, H=2 rows, values:

A B C   (y=0)
D E F   (y=1)

Pixel coordinates: A=(x=0,y=0), B=(x=1,y=0), C=(x=2,y=0), D=(x=0,y=1), E=(x=1,y=1), F=(x=2,y=1)

Shape convention 1: (H, W) = (2, 3) — NumPy/matrix convention, y-first

Index as arr[y, x].

Order	Formula	Memory layout
C order (last=x fastest)	flat = y·3 + x	A B C D E F
F order (first=y fastest)	flat = x·2 + y	A D B E C F

Shape convention 2: (W, H) = (3, 2) — ImgLib2/spatial convention, x-first

Index as arr[x, y].

Order	Formula	Memory layout
C order (last=y fastest)	flat = x·2 + y	A D B E C F
F order (first=x fastest)	flat = y·3 + x	A B C D E F

Key observation: NumPy (H,W) C-order and ImgLib2 (W,H) F-order produce identical bytes in memory (A B C D E F). They're two descriptions of the same physical layout — just different conventions for naming the axes.

Which physical axis (x vs y) is "last" depends entirely on whether you put x or y first in the shape tuple:

• Shape (H, W) → last dim = x (columns) → C order = scan row by row
• Shape (W, H) → last dim = y (rows) → F order = scan column by column

NumPy uses (H, W) by default and C order, while ImgLib2 uses (W, H) (spatial order, x-first) and F order — they arrive at the same memory layout from opposite directions.

Whether (W, H) or (H, W) is the natural convention is entirely a matter of tradition:

• Linear algebra / matrix math tradition: (rows, cols) = (H, W) — you address a matrix as M[row][col]. NumPy, MATLAB, scikit-image, most statistics libraries follow this.
• Graphics / coordinate tradition: (X, Y) = (W, H) — you address a pixel as img(x, y). ImgLib2, OpenGL, most game engines, Photoshop, GIMP, PIL's .size property follow this.

Neither is objectively more standard. NumPy is dominant in scientific Python but that doesn't make (H, W) universally natural. For anyone coming from graphics or coordinate geometry, (W, H) is completely intuitive. Both traditions are coherent within themselves.

The practical consequence for Appose users: if you create an NDArray with F_ORDER (W, H, ...) dims on the Java side — as ImgLib2 does — Python will see C_ORDER (H, W, ...). Same bytes, reversed shape tuple, different index conventions on each side. You just need to know which convention each tool uses.

The Appose wire format "reversal"

When an ImgLib2 / Appose NDArray with F-order shape (W=3, H=2) crosses the IPC boundary:

• Java: F_ORDER, shape=(3, 2) → serialize as C_ORDER → shape=(2, 3)
• Python: C_ORDER, shape=(2, 3) → arr[y, x], 2 rows × 3 cols

The shape tuple looks reversed (3,2 → 2,3), but the raw bytes are unchanged. Python's arr[y,x] accesses the same element as Java's img(x,y). This is correct behavior — it's a convention translation, not a data transformation.

System	Shape convention	Default order	Memory for W=3, H=2 image
NumPy	(H, W) — y first	C (last=x fastest	A B C D E F
ImgLib2	(W, H) — x first	F (first=x fastest	A B C D E F
Appose wire format	always C_ORDER	always last fastest	shape transmitted as (H, W)

The apparent shape reversal between Java and Python is not a bug — it's the necessary translation between x-first (spatial) and y-first (matrix) shape conventions, both of which happen to produce the same memory layout when combined with their respective default orders.

Here are the exact lines in appose-java where the shape reversal happens:

• Serialization (Messages.java:202): ndArray.shape().toIntArray(C_ORDER)
• Deserialization (Messages.java:284): new NDArray.Shape(C_ORDER, ints)

toIntArray(C_ORDER) on an F_ORDER shape just reverses the array (see NDArray.java:283): Arrays.setAll(iShape, i -> shape[shape.length - i - 1]);

So an F_ORDER (3, 2) becomes wire [2, 3], then is reconstructed as C_ORDER (2, 3) on the receiving end. The raw bytes in shared memory are untouched — only the shape metadata is reinterpreted. Because F_ORDER (W=3, H=2) and C_ORDER (H=2, W=3) describe the same physical memory layout, no data is lost or corrupted. It's purely a convention translation.

The consequence for the Java receiver (e.g., Groovy worker): if it sent an F_ORDER array, it gets back a C_ORDER array with reversed dims. The NDArray your Groovy/Java worker sees is never F_ORDER — the original order is not round-tripped.

"C order has the last index moving fastest" is a mathematical definition, not a value judgment. "Standard" in that sentence meant only the definition that the letter C in C_ORDER refers to — nothing more.

How to think about C order and F order

In the context of Appose, it makes more sense to me personally to think of C_ORDER and F_ORDER as what the shape means, not how memory is laid out. Yeah, these terms are used to describe both/either generally, but: with a 2D WxH image, the real standard in internal image memory layout is that we almost always have a 1D array ordered: x0y0, x1y0, x2y0, x3y0, ..., x0y1, x1y1, x2y1, x3y1, ... etc. That is: the WIDTH dimension i.e. the X VALUE i.e. the COLUMN NUMBER moves fast through memory, and the HEIGHT dimension i.e. the Y VALUE i.e. the ROW NUMBER moves slow through memory. If you write this shape as [W,H] you have the graphics tradition, if you write it as [H,W] you have the lin.alg / matrix tradition. But either way, IN MEMORY, it is C_ORDER i.e. "row-major" i.e. the we see all columns of a row as we stride through memory sequentially. Therefore, saying the "ImgLib2 is F_ORDER" feels intuitively wrong to me—it's not that ImgLib2 images have an F_ORDER MEMORY LAYOUT, it's that they have an F_ORDER DIMENSIONAL INDEXING ORDER. Our language when we talk about this is somehow imprecise.

To be more precise: C_ORDER and F_ORDER in NDArray.Shape describe the indexing convention of the shape tuple, not the physical memory layout. The same bytes can be correctly described by either:

• F_ORDER shape (W=3, H=2) — "first index (X) is the fast axis"
• C_ORDER shape (H=2, W=3) — "last index (X) is the fast axis"

Both describe identical memory: x0y0, x1y0, x2y0, x0y1, x1y1, x2y1. The bits don't move. Only the labeling changes. So yes: "ImgLib2 is F_ORDER" means ImgLib2 uses (W, H, ...) shape labeling with first-index-fastest semantics — it says nothing different about the actual byte arrangement than "NumPy is C_ORDER with (H, W, ...)". The language is genuinely imprecise when the word "order" is used for both things simultaneously.

Is Appose's order flipping behavior fully correct?

It is worth asking seriously whether Appose's current shape order flipping is always best. Right now, the wire format discards the original order:

• Java sends: F_ORDER (3, 2) → wire: [2, 3] as C_ORDER
• Groovy gets: C_ORDER (2, 3) ← original F_ORDER convention is lost

For a Java → Python trip this is fine: Python/NumPy uses (H, W) C_ORDER convention, so receiving (2, 3) is exactly right.

For a Java → Groovy worker, a Groovy worker that wraps the received NDArray back into an ImgLib2 ShmImg would see dims (2, 3) in C_ORDER. ImgLib2 will then still interpret this as X=3, Y=2 because the order is marked as C order accordingly—but internally, the Java Shape object goes from (3, 2) F_ORDER on the service JVM to (2, 3) C_ORDER on the worker JVM, backwards from the "default" ImgLib2 convention internally. Does this actually matter in practice? Probably not, but it's an oddity nonetheless.

[ctrueden]

The revised documentation—explaining this hopefully better but still succinctly—will be available shortly from https://docs.apposed.org/en/latest/core-concepts.html#shape-and-axis-order