Merge pull request #73 from dgault/readme-changelog

Update ReadMe and Change Log

CHANGELOG.md

@@ -1,3 +1,40 @@
+0.5.0 (June 2024)
+-----------------
+
+- Updated GitHub Actions to v4 and now deploying snapshot on tag [#80](https://github.com/ome/ZarrReader/pull/80)
+- Added Java 17 to the test matrix [#81](https://github.com/ome/ZarrReader/pull/81)
+- Bumped the Bio-Formats version to 7.1.0 [#71](https://github.com/ome/ZarrReader/pull/71)
+- Introduced S3FileSystemStore and a new option (omezarr.alt_store) for reading directly from S3 [#82](https://github.com/ome/ZarrReader/pull/82)
+
+0.4.1 (February 2024)
+---------------------
+
+- Reduced the number of fields saved in memo files [#78](https://github.com/ome/ZarrReader/pull/78)
+
+0.4.0 (December 2023)
+---------------------
+
+- Updated JZarr dependency to use dev.zarr:jzarr 0.4.0 [#54](https://github.com/ome/ZarrReader/pull/54)
+- Removed duplicate declaration from POM file [#56](https://github.com/ome/ZarrReader/pull/56)
+- Use canonical path for calls to ZarrService [#57](https://github.com/ome/ZarrReader/pull/57)
+- Updated GitHub actions checkout to V3 [#59](https://github.com/ome/ZarrReader/pull/59)
+- Updated ReadMe installation instructions and requirements [#62](https://github.com/ome/ZarrReader/pull/62)
+- Implemented performance improvements and introduced new reader options [#64](https://github.com/ome/ZarrReader/pull/64)
+- Bumped the Bio-Formats version to 7.0.0 [#65](https://github.com/ome/ZarrReader/pull/65)
+- Bumped dev.zarr:jzarr to 0.4.2 [#66](https://github.com/ome/ZarrReader/pull/66)
+
+0.3.1 (March 2023)
+------------------
+
+- Updated GitHub Actions output commands [#42](https://github.com/ome/ZarrReader/pull/42)
+- Upgraded GitHub Actions setup-java action [#47](https://github.com/ome/ZarrReader/pull/47)
+- Fixed handling of pre-existing plate metadata to avoid duplicate keys [#49](https://github.com/ome/ZarrReader/pull/49)
+
+0.3.0 (June 2022)
+-----------------
+
+- Updated a number of dependencies [#38](https://github.com/ome/ZarrReader/pull/38)
+
 0.2.0 (May 2022)
 ------------------
 

README.md

@@ -36,6 +36,10 @@ and adding the dependency:
 </dependency>
 ```
 
+### Releases
+
+Release versions of OMEZarrReader are also available directly from the [OME artifactory](https://artifacts.openmicroscopy.org/artifactory/webapp/browserepo.html?0&pathId=ome.releases:ome/OMEZarrReader)
+
 ### Bio-Formats tools
 
 If you would like to use OMEZarrReader with the bftools suite, you will need to set the `BC_CP`
@@ -45,11 +49,28 @@ environment variable to include the jar which includes all dependencies:
 BF_CP=target/OMEZarrReader-with-dependencies.jar showinf -nopix your.ome.zarr/.zattrs
 ```
 
-## Known Issues/TODO list
-- Currently working on packaging, discovered issue when connecting to S3 using packaged jar
-- S3 File System Store is likely not ideal sceanrio, other options to be investigated
-- S3 access currently very inefficient
-- Odd issue with data being lost when decompressing bytes in jzarr, an ugly hack is currently in place
-- Identification of S3 location needs updating
-- Refactor code to remove duplication
-- Parse colours for labels
+## Reader specific options
+
+The OMEZarrReader has a number of reader specific options in version 0.4.0 which can be used to customise the reader behaviour. This options can be used in the same manner as the reader options for Bio-Formats outlined [here](https://bio-formats.readthedocs.io/en/latest/formats/options.html#usage). 
+
+The new default behaviour of the `omezarr.include_labels` option introduced in v0.4.0 represents a change in behaviour from the v0.3 releases. Previously any Zarr arrays found in the labels folder would by default be represented as an additional image series. With the current default settings, Zarr arrays in the labels folder will no longer be included in the list of image series. Changing this setting to `true` will revert to the previous behaviour. 
+
+**Note:** If you had imported data with labels into OMERO using version v0.3 or earlier then you will need to ensure that the `omezarr.include_labels` option is set to true. You can do this by adding a `bfoptions` file to the fileset. This will require running psql commands to update the database to include the new `bfoptions` file. If you need help with this scenario then please contact us on [image.sc](https://forum.image.sc/).
+
+In version v0.5.0 a new option `omezarr.alt_store` was added. This allows for the source of an alternative file store to be configured. Setting the option means the pixel data to be read from a different source than originally used when initialising the reader. The initial implementation was intended for use with the [IDR] (https://idr.openmicroscopy.org/), allowing IDR to read data directly from an S3 location. The current implementation only allows for S3 access when using a public https endpoint with unauthenticated access using anonymous credentials. A more complete, general purpose implementation will follow in a future release.
+
+An example of how this could be used would be to download locally a public dataset such as [6001240.zarr] (https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.4/idr0062A/6001240.zarr). Setting the option as below, either via the API or using a `bfoptions` file, will allow you to call setID on the local file but have the pixel data read from the public S3 endpoint.
+
+```
+omezarr.alt_store = https://uk1s3.embassy.ebi.ac.uk/idr/zarr/v0.4/idr0062A/6001240.zarr
+```
+
+The list of available options are below:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `omezarr.quick_read` | false | Improves the read performance by limiting the number of files that are parsed. This assumes that the shape and resolution count of all images in a plate remains constant  |
+| `omezarr.save_annotations` | false | Determines if all the Zarr JSON metadata should be stored as XML annotations in the OME Model |
+| `omezarr.list_pixels` | true | Used to decide if getUsedFiles should list all of the pixel chunks |
+| `omezarr.include_labels` | false | Used to decide if images stored in the label sub folder should be included in the list of images |
+| `omezarr.alt_store` | null | Used to provide the location of an alternative file store where the data is located |