Modularize core ImgLib2 projects

[tpietzsch]

We want to add JPMS module descriptors to the core ImgLib2 artefacts. This issue tracks overall progress on this.

Which repos should be included in this effort?

Which repos should become imglib2 modules (vs. just being updated to use the modularized jars)?

Here is a list of the projects currently in the imglib2 Github org:

$ gh repo list imglib --no-archived
NAME                                    DESCRIPTION                                                         
imglib/.github                          ImgLib organization profile                                        
imglib/dotfiles                         Configuration files for ImgLib2 resources                           
imglib/imglib2                          A generic next-generation Java library for image processing         
imglib/imglib2-advanced-workshop        ImgLib2 Advanced Workshop                                           
imglib/imglib2-algorithm                Image processing algorithms for ImgLib2                             
imglib/imglib2-algorithm-fft            Fast Fourier Transform routine for ImgLib2                          
imglib/imglib2-algorithm-gpl            Image processing algorithms for ImgLib2 (GPL-licensed)              
imglib/imglib2-blog                     ImgLib2 news and tutorials                                          
imglib/imglib2-cache                    Cache interfaces and java.lang.ref based implementation.            
imglib/imglib2-cache-examples           Examples that illustrate imglib2-cache and cached images            
imglib/imglib2-cache-python                                                                                 
imglib/imglib2-ij                       Translation between ImgLib & ImageJ data structures (both 1.x and 2)
imglib/imglib2-imglyb                                                                                       
imglib/imglib2-introductory-workshop    ImgLib2 Introductory Workshop                                       
imglib/imglib2-jmh                                                                                          
imglib/imglib2-mesh                     Proposal for a Java mesh library                                    
imglib/imglib2-realtransform                                                                                
imglib/imglib2-roi                      Regions of interest (ROIs) and labelings for ImgLib2                
imglib/imglib2-roi-io                                                                                       
imglib/imglib2-tests                    ImgLib tests that are not bound to specific ImgLib projects         
imglib/imglib2-tutorials                Examples how to work with ImgLib2                                   
imglib/imglib2-unsafe                                                                                       
imglib/imglib2-www                      Landing page for imglib2/BDV projects                               
imglib/imglyb                           Connecting Java/ImgLib2 + Python/NumPy
imglib/imglyb-bdv                       Bdv extensions for imglyb                                           
imglib/imglyb-examples                                                                                      
imglib/imglyb-learnathon                                                                                    

Of these, the following are potential candidates for modularization:
(The others are non-Java repositories)

NAME                                    DESCRIPTION                                                         
imglib/imglib2                          A generic next-generation Java library for image processing         
imglib/imglib2-advanced-workshop        ImgLib2 Advanced Workshop                                           
imglib/imglib2-algorithm                Image processing algorithms for ImgLib2                             
imglib/imglib2-algorithm-fft            Fast Fourier Transform routine for ImgLib2                          
imglib/imglib2-algorithm-gpl            Image processing algorithms for ImgLib2 (GPL-licensed)              
imglib/imglib2-cache                    Cache interfaces and java.lang.ref based implementation.            
imglib/imglib2-cache-examples           Examples that illustrate imglib2-cache and cached images            
imglib/imglib2-cache-python
imglib/imglib2-ij                       Translation between ImgLib & ImageJ data structures (both 1.x and 2)
imglib/imglib2-imglyb                                                                                       
imglib/imglib2-introductory-workshop    ImgLib2 Introductory Workshop                                       
imglib/imglib2-jmh                                                                                          
imglib/imglib2-mesh                     Proposal for a Java mesh library                                    
imglib/imglib2-realtransform                                                                                
imglib/imglib2-roi                      Regions of interest (ROIs) and labelings for ImgLib2                
imglib/imglib2-roi-io                                                                                       
imglib/imglib2-tests                    ImgLib tests that are not bound to specific ImgLib projects         
imglib/imglib2-tutorials                Examples how to work with ImgLib2                                   
imglib/imglib2-unsafe                                                                                       

Of these repositories, the following contain test or example code.
They don't have released artefacts or dependants.
They should be kept working, but do not need to be modularized themselves.

NAME                                    DESCRIPTION                                                         
imglib/imglib2-advanced-workshop        ImgLib2 Advanced Workshop                                           
imglib/imglib2-cache-examples           Examples that illustrate imglib2-cache and cached images            
imglib/imglib2-introductory-workshop    ImgLib2 Introductory Workshop                                       
imglib/imglib2-jmh                                                                                          
imglib/imglib2-tests                    ImgLib tests that are not bound to specific ImgLib projects         
imglib/imglib2-tutorials                Examples how to work with ImgLib2                                   

The following are related to imglyb (Python bindings).
They should be included in the modularization, but they will probably have no (Java) dependants.

NAME                                    DESCRIPTION                                                         
imglib/imglib2-cache-python
imglib/imglib2-imglyb                                                                                       
imglib/imglib2-unsafe                                                                                       

That means we will focus on the following repos first:

NAME                                    DESCRIPTION                                                         
imglib/imglib2                          A generic next-generation Java library for image processing         
imglib/imglib2-algorithm                Image processing algorithms for ImgLib2                             
imglib/imglib2-algorithm-fft            Fast Fourier Transform routine for ImgLib2                          
imglib/imglib2-algorithm-gpl            Image processing algorithms for ImgLib2 (GPL-licensed)              
imglib/imglib2-cache                    Cache interfaces and java.lang.ref based implementation.            
imglib/imglib2-ij                       Translation between ImgLib & ImageJ data structures (both 1.x and 2)
imglib/imglib2-mesh                     Proposal for a Java mesh library                                    
imglib/imglib2-realtransform                                                                                
imglib/imglib2-roi                      Regions of interest (ROIs) and labelings for ImgLib2                
imglib/imglib2-roi-io                                                                                       

Split packages

At the very minimum, we have to fix instances where the same package is used in two different artefacts.
JPMS disallows splitting packages over module boundaries.

The following split packages exist currently in the core imglib2 repos:

package	projects
net.imglib2.type.numeric	imglib2-unsafe, imglib2
net.imglib2.type.numeric.complex	imglib2-unsafe, imglib2
net.imglib2.type.numeric.real	imglib2-unsafe, imglib2
net.imglib2.type	imglib2-unsafe, imglib2
net.imglib2.display.projector	imglib2-ij, imglib2
net.imglib2.img.basictypeaccess	imglib2-unsafe, imglib2
net.imglib2.img	imglib2-ij, imglib2-unsafe, imglib2
net.imglib2.type.numeric.integer	imglib2-unsafe, imglib2
net.imglib2.algorithm.region	imglib2-algorithm-gpl, imglib2-algorithm
net.imglib2.algorithm.math	imglib2-algorithm-gpl, imglib2-algorithm
net.imglib2.algorithm.fft2	imglib2-algorithm-fft, imglib2-algorithm-gpl

Repo name vs. Automatic module name vs. Package prefix

Before we add module descriptors, we can already decide on module names using the
<package-name> property in the POM of the respective project.
Via pom-scijava, this property is used to set the Automatic-Module-Name property in the jar's MANIFEST.mf.
This will then be used by the JPMS when the plain jars are put on the module path.

Ideally, project name, module name, and package prefix should all match:
If the repo is called imglib2-ij then all the classes should be in packages with prefix net.imglib2.ij.
And the automatic module name should also be net.imglib2.ij

The following is a list of the current automatic module names and package prefixes.
Problems, where they don't match up are highlighted.

project	automatic module name	package prefix
imglib2	net.imglib2	net.imglib2
imglib2-algorithm	net.imglib2.algorithm	net.imglib2
imglib2-algorithm-fft	net.imglib2.algorithm.fft2	net.imglib2.algorithm.fft2
imglib2-algorithm-gpl	net.imglib2.algorithm	net.imglib2.algorithm
imglib2-cache	net.imglib2.cache	net.imglib2.cache
imglib2-ij	net.imglib2.img	net.imglib2
imglib2-mesh	net.imglib2.mesh	net.imglib2.mesh
imglib2-realtransform	net.imglib2.realtransform	net.imglib2.realtransform
imglib2-roi	net.imglib2.roi	net.imglib2
imglib2-roi-io	net.imglib2.roi.io	net.imglib2.roi.io.labeling
imglib2-cache-python	net.imglib2.cache.python	net.imglib2.cache.python
imglib2-imglyb	net.imglib2.python	net.imglib2.python
imglib2-unsafe	UNDEFINED	net.imglib2

Resolving these problems will also resolve split packages.

First steps

We'll start by fixing imglib2-ij. imglib/imglib2-ij#37

To update dependent projects, we need tooling to

• Find all occurrences of specific classes, and update package names.
• Create PRs to the dependent projects.

[tpietzsch]

Find all occurrences of specific classes, and update package names.

https://github.com/imglib/modularization has python scripts to find usage of specific classes in repositories that are managed in pom-scijava.