# Geff Community Meeting August 2025
August 14, 2025, 8am ET
Attendees: Morgan, Caroline, Ko, Draga, Laura, Mark, Talley

## Java code base updates

- Tobi working on integrating n5-zarr library into java geff [PR](https://github.com/live-image-tracking-tools/geff-java/pull/3)
- May be waiting on the v1 release of the spec

## Python code base updates

### Breaking changes incoming!
{%preview https://github.com/live-image-tracking-tools/geff/pull/292 %}
Versioning updates coming too (see spec discussion later)
- If help is needed updating any downstream code, ping Caroline or Morgan

### Var length props
- Updated PropMetadata https://github.com/live-image-tracking-tools/geff/pull/302
- Making PropMetadata mandatory (including making the writers write it) https://github.com/live-image-tracking-tools/geff/pull/305
- Next - actually implement the var length props and string reading/writing

### Other larger efforts
- testing and validation
- reorganize and complete the data validation functions
- reorganize the tests of the reference implementations to be consistent and use the validators
- unified `write` function (instead of `write_rx`, `write_sg`)
- sets of nodes and edges and their properties (e.g. precursor to geffception)

### Help!
Here are some issue we could use help with:
{%preview https://github.com/live-image-tracking-tools/geff/issues/272 %}
{%preview https://github.com/live-image-tracking-tools/geff/issues/241 %}
{%preview https://github.com/live-image-tracking-tools/geff/issues/217 %}
{%preview https://github.com/live-image-tracking-tools/geff/issues/96 %}
{%preview https://github.com/live-image-tracking-tools/geff/issues/211 %}
{%preview https://github.com/live-image-tracking-tools/geff/issues/227 %}
{%preview https://github.com/live-image-tracking-tools/geff/issues/173 %}

Plus whatever we decide about the affine

## Specification

### Versioning
We will have one repo with two python libraries that are versioned independently.

#### geff-spec
This library will define the specification. It will have the pydantic models for the schema and the markdown of the written specification.

It will be versioned: vSX.SY.Z

change SX = breaking spec change (e.g. field/type renaming/removal, change to on-disk requirements)
change SY = non-breaking spec change (e.g. field addition)
change Z = just a bump in the pydantic model or written specification (e.g. typos)

Geff spec is *just* SX.SY.
pydantic python geff-spec version is the full trio

#### geff (reference implementation)
This library will contain all the rest of the python code - validators, reference implementations, converters, cli tools. It will depend on `geff-spec`.
vX.Y.Z.SX.SY

Change X = major feature *breaking* change
Change Y = non-breaking feature release
Change Z = bug fix release

change SX = (same as above)
change SY = (same as above)

bumping SX necessitates a bump to minimally Y...
would only bump X if is concomitant with a breaking geff-lib change
bumping SY probably requires bump to Y to support the new schema

#### Repo structure

repo/
  packages/
    geff-spec/
        src/
            geff-spec/
        tests/
        pyproject.toml
    geff/
        src/
            geff/
        tests/
        pyproject.toml
  pyproject.toml # do we need the top level pyproject?

#### Discussion
- What would happen if a user pinned geff-spec to a lower version, but did not pin geff?
- If the goal of geff is to always maintain backwards compatibility, it may not be necessary
- `write` should have an argument for specifying the major version of the spec so that we are backwards compatible on both read and write
- Versioning/releasing the schema/spec separately will make it easier to move python and java implementations forward in parallel
- Chose "geff-spec" as the name over "geff-schema" because there are a lot of things that define a geff that cannot be encoded in the schema and must instead live in the spec with language like "must" and "should"
- Ideally keep all docs for both implementation and spec in the same place, but the biggest priorty is discoverability and ease of going back and forth
-

### Units
[PR where Talley and Mark had a good discussion](https://github.com/live-image-tracking-tools/geff/pull/285)
Summary:
- Our current behavior is to accept anything for units but warn if not in OME-zarr units.
- Spec: Units, if provided, `SHOULD` be in the OME-zarr list of units.
- Mark's PR adds raising an error if the provided unit is not in pint's default registry.
- Spec: Units, if provided, `SHOULD` be in OME-zarr list and `MUST` be in pint's default registry.
- Question 1: `SHOULD` or `MUST`?
- Draga: would hate to error if you give a wrong unit, but a warning could be helpful (e.g. for typo checking). If it's not recognized, it's just an unkown unit that is maybe only for you.
- Talley: A "SHOULD" is not that useful. Better than nothing: "Look here and find something unit-y". But downstream things cannot rely on the thing in "unit" to be something we recognize, and need to implement their own validation
- If you don't have a known unit, you can't write the geff? Yes, if it's a must. But units are not required.
- Concept of a normative geff - it's a should with checking (user can know if it follow the should)
- Question 2: OME-zarr units or pint units? (I do not like mixing, we should pick one).
- conclusions: we need a defined list of things that can be stored on disk.
- pint can be a python API convenience to cast to the OME-zarr units
- EG of unit casting
- seconds -> second
- sec -> second
- Maybe OME-zarr/ngff units aren't ready to be relied upon
- Plan: make a proposal based on this conversation for the next meeting for final decision

### Affine model
{%preview https://github.com/live-image-tracking-tools/geff/issues/274 %}

- Draga: initial motivation was storing scale information, but then it got expanded into a broader affine
- NGFF is still in the process of figuring out how to incorporate it into their spec (basic functionality may be there but greater sophistication is coming)
- This may be a slow process
- Let's revisit at next meeting with a more thorough review and suggestion

## Geffception?
- Yoh and Laura are working on a test geffception file that doesn't change anything to the current library/spec
- We will review the example and hopefully have identified issues that would require changes to the library at the next meeting

## Things to add to next meeting agenda
- Affine proposal
- Units proposal
- Geffception update