search

imglib / imglib2

A generic next-generation Java library for image processing
http://imglib2.net/
Other
293 stars 93 forks source link

Modularize core ImgLib2 projects #353

Open tpietzsch opened 6 months ago

tpietzsch commented 6 months ago

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. https://github.com/imglib/imglib2-ij/issues/37

To update dependent projects, we need tooling to

tpietzsch commented 6 months ago

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.