From 6d3ce6a05d23d832ede5a8499787830624415d47 Mon Sep 17 00:00:00 2001 From: Sean Arms <67096+lesserwhirls@users.noreply.github.com> Date: Tue, 23 Jun 2026 10:02:22 -0600 Subject: [PATCH 1/3] spotless --- grib/src/test/java/ucar/nc2/grib/grib2/TestPds41.java | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/grib/src/test/java/ucar/nc2/grib/grib2/TestPds41.java b/grib/src/test/java/ucar/nc2/grib/grib2/TestPds41.java index 27cbc7c085..c6b01d5af2 100644 --- a/grib/src/test/java/ucar/nc2/grib/grib2/TestPds41.java +++ b/grib/src/test/java/ucar/nc2/grib/grib2/TestPds41.java @@ -15,7 +15,8 @@ import org.junit.runners.JUnit4; /** - * Test data from Meteo Swiss CH2 https://data.geo.admin.ch/browser/#/collections/ch.meteoschweiz.ogd-forecasting-icon-ch2?.language=en + * Test data from Meteo Swiss CH2 + * https://data.geo.admin.ch/browser/#/collections/ch.meteoschweiz.ogd-forecasting-icon-ch2?.language=en * Pollen Grasses Data (POACsnc parameter) was used to create a .gbx9 file for testing. *

* PDS (Secton 4) output from ecCodes grib_dump at the end of the file, uses as a basis for From 9cc3597b9e468b2ff7a645957afe404b6566bd86 Mon Sep 17 00:00:00 2001 From: Sean Arms <67096+lesserwhirls@users.noreply.github.com> Date: Tue, 23 Jun 2026 05:48:02 -0600 Subject: [PATCH 2/3] Add CDM Section Specification documentation Fixes Unidata/netcdf-java#1528 --- .../sidebars/netcdfJavaTutorial_sidebar.yml | 4 ++ .../pages/netcdfJava/SectionSpecification.md | 61 +++++++++++++++++++ .../cdmdatasets/readingcdm.md | 7 ++- 3 files changed, 70 insertions(+), 2 deletions(-) create mode 100644 docs/src/site/pages/netcdfJava/SectionSpecification.md diff --git a/docs/src/site/_data/sidebars/netcdfJavaTutorial_sidebar.yml b/docs/src/site/_data/sidebars/netcdfJavaTutorial_sidebar.yml index 0e2505da29..fa954650a8 100644 --- a/docs/src/site/_data/sidebars/netcdfJavaTutorial_sidebar.yml +++ b/docs/src/site/_data/sidebars/netcdfJavaTutorial_sidebar.yml @@ -159,6 +159,10 @@ entries: url: /arraystructures_ref.html output: web, pdf + - title: CDM Section Specification + url: /section_specification_ref.html + output: web, pdf + - title: CDM Calendar Date Handling url: /cdm_calendar_date_time_ref.html output: web, pdf diff --git a/docs/src/site/pages/netcdfJava/SectionSpecification.md b/docs/src/site/pages/netcdfJava/SectionSpecification.md new file mode 100644 index 0000000000..72f48b4b0c --- /dev/null +++ b/docs/src/site/pages/netcdfJava/SectionSpecification.md @@ -0,0 +1,61 @@ +--- +title: Section Specification +last_updated: 2026-06-23 +sidebar: netcdfJavaTutorial_sidebar +toc: false +permalink: section_specification_ref.html +--- +## CDM Section Specification + +### Syntax + +Array sections can be specified with Fortran 90 array section syntax, using zero-based indexing. For example: + +`/group1/group2/varName(12:22,0:100:2,:,17)` + +specifies an array section for a four-dimensional variable: + +1. `12:22` includes all the elements from 12 to 22 inclusive +1. `0:100:2` includes the elements from 0 to 100 inclusive, with a stride of 2 +1. `:` includes all the elements +1. `17` includes just the 18th element. + +For structures, you can specify nested selectors, e.g. `record(12).wind(1:20,:,3)` does a selection on the `wind` member variable of the `record` structure at index 12. +If you don’t specify a section, it means read the entire variable, e.g. `record.wind` means all the data in all the wind variables in all the record structures. + +Formally: + +``` +sectionSpec := selector | selector '.' selector +selector := varName ['(' sectionSpec ')'] +varName := STRING +sectionSpec := dim | dim ',' sectionSpec +dim := ':' | slice | start ':' end | start ':' end ':' stride + + +slice := INTEGER +start := INTEGER +stride := INTEGER +end := INTEGER +STRING := String with escaped chars = '.', '/', '(', and ')' +``` + +where: + +* Nonterminals are in lower case, terminals are in upper case, and literals are in single quotes. +* Optional components are enclosed between square braces `[` and `]`. + +TBD: + +* escape mechanism is currently %xx , mostly following opendap +* not sure if any other chars need to be escaped. + +### Restrictions + +A Sequence is a one-dimensional Structure with a variable length, it cannot be subsetted. + +A variable long name must be used, that is with its group names: `/group1/group2/varName` + +### Use + +`public Array NetcdfFile.readSection(String variableSection);` diff --git a/docs/src/site/pages/netcdfJava_tutorial/cdmdatasets/readingcdm.md b/docs/src/site/pages/netcdfJava_tutorial/cdmdatasets/readingcdm.md index 60e3802765..eeddb81ea0 100644 --- a/docs/src/site/pages/netcdfJava_tutorial/cdmdatasets/readingcdm.md +++ b/docs/src/site/pages/netcdfJava_tutorial/cdmdatasets/readingcdm.md @@ -54,6 +54,7 @@ Note that you can edit the `Variable`'s ranges (`T(0:30:10, 1, 0:3)` in this exa These are expressed with Fortran 90 array section syntax, using zero-based indexing. For example, `varName( 12:22 , 0:100:2, :, 17)` specifies an array section for a four dimensional variable. The first dimension includes all the elements from 12 to 22 inclusive, the second dimension includes the elements from 0 to 100 inclusive with a stride of 2, the third includes all the elements in that dimension, and the fourth includes just the 18th element. +The [CDM section specification](section_specification_ref.html) describes the section string syntax in more detail. The following code to dump data from your program is equivalent to the above ToolsUI actions: @@ -98,20 +99,22 @@ Or suppose you want to loop over all time steps, and make it general to handle a In this case, we call reduce(0), to reduce dimension 0, which we know has length one, but leave the other two dimensions alone. Note that `varShape` holds the total number of elements that can be read from the variable; `origin` is the starting index, and `size` is the number of elements to read. -This is different from the Fortran 90 array syntax, which uses the starting and ending array indices (inclusive): +This is different from the section (Fortran 90) array syntax, which uses the starting and ending array indices (inclusive): {% capture rmd %} {% includecodeblock netcdf-java&docs/src/test/java/examples/cdmdatasets/ReadingCdmTutorial.java&readSubset %} {% endcapture %} {{ rmd | markdownify }} -If you want strided access, you can use the Fortran 90 string routine: +If you want strided access, you can use the section string method: {% capture rmd %} {% includecodeblock netcdf-java&docs/src/test/java/examples/cdmdatasets/ReadingCdmTutorial.java&readByStride %} {% endcapture %} {{ rmd | markdownify }} +The [CDM section specification](section_specification_ref.html) describes the section string syntax in more detail. + #### Reading with Range Objects For general programing, use the read method that takes a `List` of `ucar.ma2.Range` objects. From 0e0f29c51bdfb2ba57b7037b234a94543b7b5fe2 Mon Sep 17 00:00:00 2001 From: Sean Arms <67096+lesserwhirls@users.noreply.github.com> Date: Tue, 23 Jun 2026 08:34:14 -0600 Subject: [PATCH 3/3] Add conda-forge release information to the docs Closes unidata/netcdf-java#1489 --- .../developer/CdmUtilityPrograms.md | 32 +++++++++++++++---- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/src/site/pages/netcdfJava/developer/CdmUtilityPrograms.md b/docs/src/site/pages/netcdfJava/developer/CdmUtilityPrograms.md index 5ac58db8e8..d67f9d8689 100644 --- a/docs/src/site/pages/netcdfJava/developer/CdmUtilityPrograms.md +++ b/docs/src/site/pages/netcdfJava/developer/CdmUtilityPrograms.md @@ -7,7 +7,14 @@ permalink: cdm_utility_programs.html --- Below are useful command-line utilities that can be called from the CDM library. -The easiest way to use these is to grab the latest netcdfAll.jar file. +One way to use these tools is to grab the latest netcdfAll.jar or toolsUI.jar file from the [Unidata downloads page](https://downloads.unidata.ucar.edu/netcdf-java/){:target="_blank"} or the [netCDF-Java GitHub releases page](https://github.com/Unidata/netcdf-java/releases){:target="_blank"}. +However, a super handy [community-led effort](https://github.com/conda-forge/netcdf-java-feedstock){:target="_blank"} makes JAR management and a set of convenient wrapper scripts (`.sh` and `.bat`) available through `conda-forge`: + +```bash +conda install -c conda-forge netcdf-java +``` + +## Utilities * [ncdump](#ncdump): prints the textual representation of a dataset to standard output * [nccopy](#nccopy): copies a CDM dataset to a netCDF-3 (default) or netCDF-4 file @@ -17,7 +24,6 @@ The easiest way to use these is to grab the latest netcdfAll.jar file. * [CFPointWriter](#cfpointwriter): copies a CDM point feature dataset to CF/NetCDF format * [GribCdmIndex](#gribcdmindex): write GRIB Collection Indexes * [FeatureScan](#featurescan): scans a directory to find CDM datasets and determines their FeatureTypes -* [NetcdfDataset](#netcdfdataset): copies a NetcdfFile object, or parts of one, to a netcdf-3 or netcdf-4 disk file * [ToolsUI](#toolsui): Netcdf Tools user interface ## ncdump @@ -42,6 +48,7 @@ where: * `-v varName1;varName2;..`: show data for these variables, use variable’s full names (including groups if present) * `-v varName(0:1,:,12)`: show data for a section of this variable only, using FORTRAN 90 section specification +The conda wrapper script is named `ncj-ncdump`. ## nccopy @@ -88,6 +95,8 @@ java -Xmx1g -classpath netcdfAll-.jar ucar.nc2.write.Nccopy [options] Default: false ~~~ +The conda wrapper script is named `ncj-nccopy`. + ## nccompare Compares two [CDM files](file_types.html) for semantic equivalence. @@ -103,6 +112,8 @@ where * `file1`: first file to compare * `file2`: second file to compare +The conda wrapper script is named `ncj-nccompare`. + ## BufrSplitter Copies a BUFR file\'s messages into separate output files, depending on message type. @@ -116,6 +127,8 @@ where * `--fileSpec`: file to split * `--dirOut`: output directory of split operation +The conda wrapper script is named `ncj-bufrsplitter`. + ## CFPointWriter Copies a CDM point feature dataset to CF/NetCDF format. @@ -150,6 +163,8 @@ java -Xmx1g -classpath netcdfAll-.jar ucar.nc2.ft.point.writer.CFPointW Default: false ~~~ +The conda wrapper script is named `ncj-cfpointwriter`. + ## GribCdmIndex Write GRIB Collection Indexes from an XML file containing a [GRIB ``](grib_feature_collections_ref.html) XML element. @@ -175,11 +190,13 @@ java -Xmx1g -classpath netcdfAll-.jar ucar.nc2.grib.collection.GribCdmI Note that the output file is placed in the root directory of the collection, as specified by the [Collection Specification string](https://docs.unidata.ucar.edu/tds/current/userguide/collection_spec_string_ref.html){:target="_blank"} of the GRIB [``](grib_feature_collections_ref.html). +The conda wrapper script is named `ncj-gribcdmindex`. + ## FeatureScan Scans all the files in a directory to see if they are [CDM files](file_types.html) and can be identified as a particular feature type. -~~~basj +~~~bash java -Xmx1g -classpath netcdfAll-.jar ucar.nc2.ft.scan.FeatureScan directory [-subdirs] ~~~ @@ -188,6 +205,8 @@ where * `directory`: scan this directory * `-subdirs`: recurse into subdirectories +The conda wrapper script is named `ncj-featurescan`. + ## CatalogCrawler Crawl a catalog, optionally open datasets to look for problems. @@ -260,13 +279,12 @@ count fail = 3 count failException = 0 ~~~ -## NetcdfDataset - -Use [nccopy](#nccopy) instead. +The conda wrapper script is named `ncj-catalogcrawler`. ## ToolsUI ~~~bash -java -Xmx8g -jar netcdfAll-.jar +java -Xmx8g -jar toolsUI-.jar ~~~ +The conda wrapper script is named `ncj-toolsui`.