Merge branch 'master' of github.com:glencoesoftware/bioformats2raw in…

…to progress-api

.github/workflows/build.yml

@@ -11,32 +11,28 @@ jobs:
   build:
     strategy:
       matrix:
-        java: [1.8, 11, 17]
+        java: [8, 11, 17]
         os: [ubuntu-latest]
     runs-on: ${{ matrix.os }}
     env:
       gradle_commands: --stacktrace build
     steps:
       - uses: actions/checkout@v2
       - name: Set up JDK ${{ matrix.java }}
-        uses: actions/setup-java@v1
+        uses: actions/setup-java@v3
         with:
           java-version: ${{ matrix.java }}
+          distribution: 'zulu'
+          cache: "gradle"
       - name: Install libraries
         run: |
           sudo apt-get install -y libblosc1
-      - name: Cache Gradle packages
-        uses: actions/cache@v2
-        with:
-          path: ~/.gradle/caches
-          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle') }}
-          restore-keys: ${{ runner.os }}-gradle
       - name: Run commands
         run: |
           ./gradlew ${{ env.gradle_commands }}
       - name: Upload artifacts
         uses: actions/upload-artifact@v2
         with:
-          name: bioformats2raw
+          name: bioformats2raw ${{ matrix.java }}
           path: build/distributions/*.zip
           retention-days: 30

README.md

@@ -46,13 +46,34 @@ Development Installation
 
     ./gradlew tasks
 
+Configuring Logging
+===================
+
+Logging is provided using the logback library. The `logback.xml` file in `src/dist/lib/config/` provides a default configuration for the command line tool.
+In release and snapshot artifacts, `logback.xml` is in `lib/config/`.
+You can configure logging by editing the provided `logback.xml` or by specifying the path to a different file:
+
+    JAVA_OPTS="-Dlogback.configurationFile=/path/to/external/logback.xml" \
+    bioformats2raw ...
+
+Alternatively you can use the `--debug` flag, optionally writing the stdout to a file:
+
+    bioformats2raw /path/to/file.mrxs /path/to/zarr-pyramid --debug > bf2raw.log
+
+The `--log-level` option takes an [slf4j logging level](https://www.slf4j.org/faq.html#fatal) for additional simple logging configuration.
+`--log-level DEBUG` is equivalent to `--debug`. For even more verbose logging:
+
+    bioformats2raw /path/to/file.mrxs /path/to/zarr-pyramid --log-level TRACE
+
 Eclipse Configuration
 =====================
 
 1. Run the Gradle Eclipse task:
 
     ./gradlew eclipse
 
+2. Add the logback configuration in `src/dist/lib/config/` to your CLASSPATH.
+
 Usage
 =====
 
@@ -76,7 +97,8 @@ Alternatively, the `--resolutions` options can be passed to specify the exact nu
 
 
 Maximum tile dimensions can be configured with the `--tile_width` and `--tile_height` options.  Defaults can be viewed with
-`bioformats2raw --help`.
+`bioformats2raw --help`. Be mindful of the downstream workflow when selecting a tile size other than the default.
+A smaller than default tile size is rarely recommended.
 
 If the input file has multiple series, a subset of the series can be converted by specifying a comma-separated list of indexes:
 
@@ -242,6 +264,11 @@ the layout of the top-level Zarr group is now part of the upstream specification
 https://ngff.openmicroscopy.org/0.4/#bf2raw and the `OME` directory containing the
 `METADATA.ome.xml` file is now a Zarr group.
 
+Versions 0.5.0 and later write [OMERO rendering metadata](https://ngff.openmicroscopy.org/0.4/#omero-md)
+by default. This includes calculating the minimum and maximum pixel values for the entire image.
+We recommend keeping this metadata for maximum compatibility with downstream applications, but it can
+be omitted by using the `--no-minmax` option.
+
 Performance
 ===========
 
@@ -256,7 +283,7 @@ On systems with significant I/O bandwidth, particularly SATA or
 NVMe based storage, you may find sharply diminishing returns with high
 worker counts.  There are significant performance gains to be had utilizing
 larger tile sizes but be mindful of the consequences on the downstream
-workflow.
+workflow. Smaller tile sizes than the default are rarely recommended.
 
 The worker count defaults to the number of detected CPUs.  This may or may not be appropriate for the chosen input data.
 If reading a single tile from the input data requires a lot of memory, decreasing the worker count will be necessary
@@ -268,6 +295,19 @@ This is not a common case, but is a known issue with Imaris HDF data in particul
 In general, expect to need to tune the above settings and measure
 relative performance.
 
+Metadata caching
+================
+
+During conversion, a temporary `.*.bfmemo` file will be created. By default, this file is in the same directory as the input data
+and will be removed after the conversion finishes. The location of the `.*.bfmemo` file can be configured using the `--memo-directory` option:
+
+    bioformats2raw /path/to/file.mrxs /path/to/zarr-pyramid --memo-directory /tmp/
+
+This is particularly helpful if you do not have write permissions in the input data directory.
+
+As of version 0.5.0, `.*.bfmemo` files are deleted at the end of conversion by default. We do not recommend keeping these files for normal
+conversions, but if they are needed for troubleshooting then the `--keep-memo-files` option can be used.
+
 License
 =======
 

build.gradle

@@ -6,7 +6,7 @@ plugins {
 }
 
 group = 'com.glencoesoftware'
-version = '0.6.0-SNAPSHOT'
+version = '0.7.0-SNAPSHOT'
 
 mainClassName = 'com.glencoesoftware.bioformats2raw.Converter'
 sourceCompatibility = 1.8
@@ -46,14 +46,16 @@ configurations.all {
 
 dependencies {
     implementation 'net.java.dev.jna:jna:5.10.0'
-    implementation 'ome:formats-gpl:6.10.1'
+    implementation 'ome:formats-gpl:6.12.0'
     implementation 'info.picocli:picocli:4.6.1'
     implementation 'com.univocity:univocity-parsers:2.8.4'
     implementation 'com.bc.zarr:jzarr:0.3.5'
     // implementation 'org.carlspring.cloud.aws:s3fs-nio:1.0-SNAPSHOT'
     // implementation 'io.nextflow:nxf-s3fs:1.1.0'
     implementation 'org.lasersonlab:s3fs:2.2.3'
     implementation 'javax.xml.bind:jaxb-api:2.3.0'
+    implementation group: 'ch.qos.logback', name: 'logback-classic', version: '1.3.4'
+    implementation group: 'ch.qos.logback', name: 'logback-core', version: '1.3.4'
 
 
     implementation 'org.openpnp:opencv:3.4.2-1'
@@ -95,6 +97,18 @@ distributions {
     }
 }
 
+startScripts {
+  // placing logback.xml somewhere under src/dist/lib/ keeps it out of
+  // bioformats2raw-*.jar but automatically includes it in the distribution zip
+  // the directory containing logback.xml must be explicitly added to the
+  // startup scripts' classpath, otherwise it will not be detected
+
+  // a subdirectory of 'src/dist/lib/' (not just 'src/dist/') is necessary,
+  // likely due to https://issues.gradle.org/browse/GRADLE-2991
+  // see also discussion in https://github.com/glencoesoftware/bioformats2raw/pull/169
+  classpath += files('src/dist/lib/config/')
+}
+
 publishing {
     publications {
         bioformats2raw(MavenPublication) {

src/main/java/com/glencoesoftware/bioformats2raw/Colors.java

@@ -35,6 +35,7 @@ public class Colors {
   /**
    * Determine which color to use for the given channel.
    * If a channel color is already set, that will be returned.
+   * If there is only one channel, it will be set to grey.
    * If a channel emission wavelength is set, that will be used
    * to determine the color; red, green, or blue based on the
    * wavelength in nm.
@@ -53,6 +54,10 @@ public static Color getColor(OMEXMLMetadata meta, int series, int c) {
     if (color != null) {
       return color;
     }
+    // default to grey for single channel data
+    if (meta.getChannelCount(series) == 1) {
+      return new Color(128, 128, 128, 255);
+    }
 
     Length emWave = meta.getChannelEmissionWavelength(series, c);
     if (emWave != null) {