Merge pull request #3 from bengtl/main

MicroJSON - supporting pydantic 2.0

.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+  name: ci 
+  on:
+    push:
+      branches:
+        - master 
+        - main
+  permissions:
+    contents: write
+  jobs:
+    deploy:
+      runs-on: ubuntu-latest
+      steps:
+        - uses: actions/checkout@v3
+        - uses: actions/setup-python@v4
+          with:
+            python-version: 3.x
+        - uses: actions/cache@v2
+          with:
+            key: ${{ github.ref }}
+            path: .cache
+        - run: pip install mkdocs-material
+        - run: pip install pillow cairosvg
+        - run: mkdocs gh-deploy --force

README.md

@@ -1 +1,41 @@
-# microjson
+# MicroJSON
+
+MicroJSON is a JSON-based format inspired by [GeoJSON](https://geojson.org), designed to encode a variety of data structures related to microscopy images. It can handle representations of reference points, regions of interest, and other annotations, making it an ideal solution for conveying complex microscopy data in a straightforward, easy-to-use format.
+
+## Features
+
+MicroJSON offers a range of features designed to meet the needs of microscopy data representation:
+
+- **Flexible Data Structures:** MicroJSON can represent diverse data structures, including geometries (such as points, multipoints, linestrings, polygons), features (individual entities with specific properties), feature collections (groups of features), and coordinate systems.
+
+- **Standardized Format:** MicroJSON uses the widely adopted JSON format, ensuring compatibility with a wide range of programming languages and tools.
+
+- **Extensibility:** MicroJSON can handle additional properties associated with specific features, such as metadata relating to microscopy images.
+
+## Usage
+
+MicroJSON can be used with any application or tool that can process JSON data. Due to its design, it is particularly suited to applications related to the analysis, visualization, and manipulation of microscopy images.
+
+## Examples
+
+Refer to the examples foler to see samples of MicroJSON files as well as a simple parsing example, or the [example in the documentation](docs/example.md)
+
+## Specification
+
+For more detailed information about the MicroJSON structure and its components, please refer to the [Specification](docs/index.md) file.
+
+## External Resources
+
+The GeoJSON test files are copied from the [GeoJSON Schema GitHub repository](https://github.com/geojson/schema), and are Copyright (c) 2018 Tim Schaub under MIT License.
+
+## Contribution
+
+We welcome contributions to the development and enhancement of MicroJSON. Whether you're reporting bugs, suggesting enhancements, or contributing to the code, your input is highly appreciated.
+
+## License
+
+MicroJSON is licensed under [MIT License](./LICENSE).
+
+---
+
+This project is maintained by Polus AI. For any queries or further discussion, please contact [contact details].

README_short.md

@@ -0,0 +1,37 @@
+# MicroJSON
+
+MicroJSON is a JSON-based format inspired by [GeoJSON](https://geojson.org), designed to encode a variety of data structures related to microscopy images. It can handle representations of reference points, regions of interest, and other annotations, making it an ideal solution for conveying complex microscopy data in a straightforward, easy-to-use format.
+
+## Features
+
+MicroJSON offers a range of features designed to meet the needs of microscopy data representation:
+
+- **Flexible Data Structures:** MicroJSON can represent diverse data structures, including geometries (such as points, multipoints, linestrings, polygons), features (individual entities with specific properties), feature collections (groups of features), and coordinate systems.
+
+- **Standardized Format:** MicroJSON uses the widely adopted JSON format, ensuring compatibility with a wide range of programming languages and tools.
+
+- **Extensibility:** MicroJSON can handle additional properties associated with specific features, such as metadata relating to microscopy images.
+
+## Usage
+
+MicroJSON can be used with any application or tool that can process JSON data. Due to its design, it is particularly suited to applications related to the analysis, visualization, and manipulation of microscopy images.
+
+## External Resources
+
+The GeoJSON test files are copied from the [GeoJSON Schema GitHub repository](https://github.com/geojson/schema), and are Copyright (c) 2018 Tim Schaub under MIT License.
+
+## Contribution
+
+We welcome contributions to the development and enhancement of MicroJSON. Whether you're reporting bugs, suggesting enhancements, or contributing to the code, your input is highly appreciated.
+
+## License
+
+MicroJSON is licensed under MIT License, (c) 2023 Polus AI & Nextonic Solutions LLC.
+
+## Authors
+Bengt Ljungquist [bengt.ljungquist@nextonicsolutions.com](bengt.ljungquist@nextonicsolutions.com)
+
+
+---
+
+This project is maintained by Polus AI. For any queries or further discussion, please contact the author on email address above.

docs/example.md

@@ -0,0 +1,144 @@
+# MicroJSON Examples
+## Basic MicroJSON
+This JSON file demonstrates how MicroJSON can be used to define and describe different structures related to imaging, such as cells and their nuclei, including their spatial relationships, identifiers, labels, and color representations.
+
+```json
+{
+    "type": "FeatureCollection",
+    "features": [
+      {
+        "type": "Feature",
+        "geometry": {
+          "type": "Polygon",
+          "subtype": "Rectangle",
+          "coordinates": [[[0.0, 0.0], [0.0, 50.0], [50.0, 50.0], [50.0, 0.0], [0.0, 0.0]]]
+        },
+        "properties": {
+            "string": {
+                "well": "A1"
+            },
+            "numeric": {
+                "cellCount": 5 
+            },
+            "multi-numeric": {
+                "ratioInfectivity": [[0.1, 0.2, 0.3, 0.4, 0.5], [0.2, 0.3, 0.4, 0.5, 0.6]]
+            }
+        }
+      },
+      {
+        "type": "Feature",
+        "geometry": {
+          "type": "Polygon",
+          "subtype": "Rectangle",
+          "coordinates": [[[50.0, 0.0], [50.0, 50.0], [100.0, 50.0], [100.0, 0.0], [50.0, 0.0]]]
+        },
+        "properties": {
+            "string": {
+                "well": "A2"
+            },
+            "numeric": {
+                "cellCount": 10 
+            },
+            "multi-numeric": {
+                "ratioInfectivity": [[0.1, 0.2, 0.3, 0.4, 0.5], [0.2, 0.3, 0.4, 0.5, 0.6]]
+            }
+        }
+      }
+    ],
+    "value_range": {
+        "cellCount": {
+            "min": 0,
+            "max": 10
+        },
+        "ratioInfectivity": {
+            "min": 0,
+            "max": 1
+        }
+    },
+    "string_fields": ["well","imagename"],
+    "coordinatesystem": {
+      "axes": [
+          {
+              "name": "x",
+              "unit": "micrometer",
+              "type": "cartesian",
+              "pixelsPerUnit": 1,
+              "description": "x-axis"
+          },
+          {
+              "name": "y",
+              "unit": "micrometer",
+              "type": "cartesian",
+              "pixelsPerUnit": 1,
+              "description": "y-axis"
+          }
+      ],
+      "transformation_matrix": [
+          [
+              1.0,
+              0.0,
+              0.0
+          ],
+          [
+              0.0,
+              1.0,
+              0.0
+          ],
+          [
+              0.0,
+              0.0,
+              0.0
+          ]
+      ]
+    }
+  }
+
+```
+
+## Stitching Vector MicroJSON
+This JSON file demonstrates how MicroJSON can be used to define and describe a stitching vector, which is used to describe the spatial relationship between multiple images that may be stitched together.
+```json
+{
+    "type": "FeatureCollection",
+    "coordinatesystem": {
+      "axes": [
+        {
+          "name": "x"
+        },
+        {
+          "name": "y"
+        }
+      ],
+    },
+    "features": [
+      {
+        "type": "Feature",
+        "geometry": {
+          "type": "Polygon",
+          "subtype": "Rectangle",
+          "coordinates": [[[0.0, 0.0], [0.0, 50.0], [50.0, 50.0], [50.0, 0.0], [0.0, 0.0]]]
+        },
+        "properties": {
+          "type": "Image",
+          "URI": "./image_1.tif"
+        }
+      },
+      {
+        "type": "Feature",
+        "geometry": {
+          "type": "Polygon",
+          "subtype": "Rectangle",
+          "coordinates": [[[50.0, 0.0], [50.0, 50.0], [100.0, 50.0], [100.0, 0.0], [50.0, 0.0]]]
+        },
+        "properties": {
+          "type": "Image",
+          "URI": "./image_2.tif"
+        }
+      }
+    ],
+    "properties": {
+      "type": "StitchingVector"
+    }
+}
+
+```

docs/index.md

@@ -0,0 +1,107 @@
+# MicroJSON Specification
+
+## Introduction
+
+MicroJSON is a format, inspired by [GeoJSON](https://geojson.org), for encoding a variety of data structures related to microscopy images, including reference points, regions of interest, and other annotations. These data structures are represented using the widely adopted JSON format, making it easy to work with in various programming languages and applications. It is fully backwards compatible with the [GeoJSON Specification, RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946), since any GeoJSON also is accepted as a MicroJSON. As GeoJSON supports foreign top level properties, a MicroJSON is also a valid GeoJSON. This specification describes briefly the objects that exist in GeoJSON, and then in more detail describes the additional objects that are part of MicroJSON. For a more detailed description of the GeoJSON objects, please see the [GeoJSON Specification, RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946).
+
+## Objects
+
+### MicroJSON Object
+
+A MicroJSON object is a JSON object that represents a geometry, feature, or collection of features, or more precisely, be either of type (having value of top level field `type` as) `"Geometry"`, `"Feature"`, or `"Featurecollection"`, that is, the same as for GeoJSON. What separates MicroJSON from GeoJSON is that it MAY have a member `"coordinatesystem"` in a Feature or FeatureCollection object:  
+
+- `"coordinatesystem"`: (Optional) A coordinate system object as defined in the section [Coordinates object](#coordinates-object). If this property is not present, the default coordinate system is assumed to be the same as the image coordinate system, using cartesian coordinates and pixels as units. It is recommended to define this property at the top level of the MicroJSON object, but it MAY also be defined at the level of a Feature or Geometry object, in which case it overrides the top level coordinate system.
+
+A MicroJSON object MAY have a `"bbox"` property":
+
+- `"bbox"`: (Optional) Bounding Box of the feature represented as an array of length 4 (2D) or length 6 (3D).
+
+
+### Geometry Object
+
+A geometry object is a JSON object where the `type` member's value is one of the following strings: `"Point"`, `"MultiPoint"`, `"LineString"`, `"MultiLineString"`, `"Polygon"`, `"Rectangle"`, `"MultiPolygon"`, or `"GeometryCollection"`.
+
+Each geometry object MUST have a `"coordinates"` member with an array value. The structure of the coordinates array depends on the geometry type.
+
+- **Point**: The coordinates array must contain two or three (if 3D) numbers representing the X and Y (and Z) coordinates of the point in the image. A “Point” Geometry MAY have a radius, if indicating a circular object, with the value in pixels, specified as a member `“radius”` of the Geometry object.
+
+- **MultiPoint**: The coordinates array must be an array of point coordinates.
+
+- **LineString**: The coordinates array must be an array of two or more point coordinates forming a continuous line. A “LineString” Geometry MAY have a radius, with the value in pixels, specified as a member “radius” of the Geometry object.
+
+- **MultiLineString**: The coordinates array must be an array of LineString coordinate arrays.
+
+- **Polygon**: The coordinates array must be an array of linear ring coordinate arrays, where the first linear ring represents the outer boundary and any additional rings represent holes within the polygon.
+
+    - A subtype of “Polygon” is the “Rectangle” geometry: A polygon with an array of four 2D point coordinates representing the corners of the rectangle in a counterclockwise order. It has the property subtype with the value `“Rectangle”`.
+
+    - A subtype of “Polygon” is the “Cuboid”: A polygon with an array of eight 3D point coordinates representing the corners of the rectangle in a counterclockwise order in the X-Y plane, starting with the plane with the lowest Z value. It has the property subtype with the value `“Cuboid”`.
+
+- **MultiPolygon**: The coordinates array must be an array of Polygon coordinate arrays.
+
+### GeometryCollection
+
+A GeometryCollection is an array of geometries (Point, multipoint, LinesString, MultiLineString, Polygon, MultiPolygon). It is possible for this array to be empty.
+
+### Feature Object
+
+A feature object represents a spatially bounded entity associated with properties specific to that entity. A feature object is a JSON object with the following members, required unless otherwise noted:
+
+- `"type"`: A string with the value `"Feature"`.
+- `"geometry"`: A geometry object as defined in the section above or a JSON null value.
+- `"properties"`: (Optional) A JSON object containing properties and metadata specific to the feature, or a JSON null value. It MAY have the following sub-properties:
+    - `"string"`: (Optional) A list with key-value pairs, with string keys and string values, e.g. `{"color": "red", "size": "large"}`.
+    - `"numeric"`: (Optional) A list with key-value pairs, with string keys and numerical values, e.g. `{"area": 123.45, "volume": 678.90}`.
+    - `"multi-numeric"`: (Optional) A list with key-value pairs, with string keys and list of numerical values, e.g. `{"area": [123.45, 234.56], "volume": [678.90, 789.01]}`.
+- `"id"`: (Optional) A unique identifier for this feature.
+- `"ref"`: (Optional) A reference to an external resource, e.g. URI to a zarr strcture, e.g. "s3://zarr-demo/store/my_array.zarr".
+
+
+#### Special Feature Objects
+
+- **Image**: An image MUST have the following key-value pairs in its “properties” object:
+
+    - `"type"`: A string with the value “Image”
+
+    - `"URI"`: A string with the image URI, e.g. “./image_1.tif"
+
+    An Image MUST also have a geometry object (as its “geometry” member) of type "Polygon", subtype “Rectangle”, indicating the shape of the image. An Image MAY have the following additional key-value pairs in its “properties” object:
+    - `"correction"`: A list of coordinates indicating the relative correction of the image, e.g. `[1, 2]` indicating a correction of 1 units in the x direction and 2 units in the y direction, with units as defined by the coordinate system. If the coordinate system is not defined, the units are pixels.
+
+### FeatureCollection Object
+
+A FeatureCollection object is a JSON object representing a collection of feature objects. A FeatureCollection object has a member with the name `"features"`. The value of `"features"` is a JSON array. Each element of the array is a Feature object as defined above. It is possible for this array to be empty. Additionally, it MAY have the following members:
+- `"string_fields"`: (Optional) A list of strings, indicating the descriptive fields of the features in the collection, e.g. `["color", "size"]`.
+- `"value_range"`: (Optional) A list of key-value pairs, with string keys and as keys another object with the fields:
+    * `"min"`: The minimum value of the field in the key (both `"numeric"` and `"multi-numeric"`) of the features in the collection, e.g. `{"area": 123.45, "volume": 678.90}`.
+    * `"max"`: The maximum value as above.
+- `"properties"`: (Optional) A JSON object containing properties and metadata specific to the feature collection, and which apply to all features of the collection, or a JSON null value. It has the same structure as the `"properties"` member of a Feature object.
+
+#### Special FeatureCollection Objects
+
+- **StitchingVector**: Represents a stitching vector, and MUST have the following key-value pairs in its “properties” object:
+
+    - `"type"`: A string with the value “StitchingVector”
+
+    Any object of a StitchingVector “features” array MUST be an “Image” special type of features object.
+
+### Coordinates Object
+
+A coordinates object represents the choice of axes (2D or 3D) and potentially their scale. It MUST have the following properties:
+
+- `"axes"`: Representing the choice of axes as an Axis object.
+
+It MAY contain the following properties:
+- `"transformation_matrix"`: Representing the transformation matrix from the coordinate system of the image to the coordinate system of the MicroJSON object. It MUST be an array of arrays of numbers, with the number of rows equal to the number of axes in the coordinate system, and the number of columns equal to the number of axes in the image coordinate system. The transformation matrix MUST be invertible.
+
+
+### Axis Object
+
+An axis object represents the choice of axes (2D or 3D). It MUST have the following properties:
+- `"name"`: Representing the name of the axis. It MUST be a string.
+It MAY contain the following properties:
+- `"unit"`: Representing the units of the corresponding axis in the axes property. It MUST be an array with the elements having any of the following values: `[“angstrom", "attometer", "centimeter", "decimeter", "exameter", "femtometer", "foot", "gigameter", "hectometer", "inch", "kilometer", "megameter", "meter", "micrometer", "mile", "millimeter", "nanometer", "parsec", "petameter", "picometer", "terameter", "yard", "yoctometer", "yottameter", "zeptometer", "zettameter“]`
+- `"pixels_per_unit"`: A decimal value, except for angles, where it SHOULD have the value “0”.
+- `"description"`: A string describing the axis.
+
+

docs/init_highlight.js

@@ -0,0 +1,5 @@
+document.addEventListener('DOMContentLoaded', (event) => {
+    document.querySelectorAll('pre code').forEach((block) => {
+      hljs.highlightBlock(block);
+    });
+  });