<html><head><meta http-equiv="Content-Type" content="text/html charset=windows-1252"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"><div>Hi,</div><div><br></div><div>very long email coming. Here is to quickly find out if you should bother reading it:</div><div>I’m preparing an update to the spim-data and bigdataviewer-core projects, that might break your code if you are using BigDataViewer or SpimData APIs.</div><div>If you are not using these APIs, then you can stop reading now -- nothing will change for users of the plugin.</div><div>If you only use BDV as a visualization frontend, then most likely you will be not affected by the changes.</div><div><b>If you wrote a BDV backend and/or SpimData ImgLoader, you WILL be affected.</b> In the following I will describe how to fix your ImgLoaders.</div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><u>First some motivation, for why this API break is necessary:</u></div><div><br></div><div>The basic idea of the API change is the following:</div><div>So far, all <font face="Monaco" style="font-size: 11px;">BasicImgLoader<T></font> and derived interfaces have been generically typed on <font face="Monaco" style="font-size: 11px;">T</font>, meaning that the ImgLoader would deliver images of type <font face="Monaco" style="font-size: 11px;">T</font> for all timepoints and setups (angles, channels, etc).</div><div>The new API moves the generic parameter one level deeper, to the setups. Now <font face="Monaco" style="font-size: 11px;">BasicImgLoader</font> is not generic. It provides one <font face="Monaco" style="font-size: 11px;">BasicSetupImgLoader<T></font> for each setup. <font face="Monaco" style="font-size: 11px;">T</font> can be different for each setup.</div><div><br></div><div>This will enable in the future to mix different types in one dataset. For example, in a multi-angle lightsheet dataset, raw you could have 16bit integer for the raw stacks of each angle, 32bit floating point for the multi-angle fusion and deconvolution result, and maybe 64 bit integers for some label fields that describe segmentation results etc. This could now all be stored in the same dataset.</div><div>The introduction of this additional <font face="Monaco" style="font-size: 11px;">BasicSetupImgLoader<T></font> interface level will also make it easy to merge datasets, where you combine in one dataset data from different sources (for example, raw data somewhere on a server, deconvolved data on a different sertver, segmentation result in local files, etc).</div><div><br></div><div><br></div><div><br></div><div><div><br></div><div><u>Where is the code?</u></div><div><br></div><div>The new API is implemented in the “types” branch of projects</div><div><a href="https://github.com/bigdataviewer/spimdata">https://github.com/bigdataviewer/spimdata</a> and</div><div><a href="https://github.com/bigdataviewer/bigdataviewer-core">https://github.com/bigdataviewer/bigdataviewer-core</a></div><div><br></div><div>In addition, I already fixed the following projects that are using the API:</div><div><a href="https://github.com/bigdataviewer/bigdataviewer-server">https://github.com/bigdataviewer/bigdataviewer-server</a></div><div><a href="https://github.com/bigdataviewer/bigdataviewer_fiji">https://github.com/bigdataviewer/bigdataviewer_fiji</a></div><div><a href="https://github.com/bigdataviewer/SPIM_Registration">https://github.com/bigdataviewer/SPIM_Registration</a></div><div><a href="https://github.com/fiji/MaMuT">https://github.com/fiji/MaMuT</a></div><div><br></div><div>Everything is on branch “types”, with SNAPSHOT couplings between these projects.</div><div>I plan to release it all in one go.</div><div><br></div></div><div><br></div><div><br></div><div><br></div><div><u>What changed exactly?</u></div><div><br></div><div>Basically, from a ImgLoader user perspective, instead of calling</div><div><span style="font-family: Monaco; font-size: 11px;">ViewId view = new ViewId( </span><span style="font-family: Monaco; font-size: 11px; color: rgb(126, 80, 79);">timepointId</span><span style="font-family: Monaco; font-size: 11px;">, </span><span style="font-family: Monaco; font-size: 11px; color: rgb(126, 80, 79);">setupId</span><span style="font-family: Monaco; font-size: 11px;"> );</span></div><div><div style="margin: 0px; font-size: 11px; font-family: Monaco;">imgloader.getImage( view );</div></div><div>you will now call</div><div><span style="font-family: Monaco; font-size: 11px;">imgloader.getSetupImgLoader( setupId</span><span style="font-family: Monaco; font-size: 11px;"> ).getImage( timepointId );</span></div><div><br></div><div>There is one more change, which is unrelated (but I think this is a good time to put it in, while breaking API anyways).</div><div>All <span style="font-family: Monaco; font-size: 11px;">getImage()</span> variants have additional optional parameter <font face="Monaco" style="font-size: 11px;">ImgLoaderHint... hints</font>.</div><div>This is used to pass hints to the ImgLoader implementations about how to best load the data. Currently, the only existing hint is <span style="text-decoration: underline; font-family: Monaco; font-size: 11px;">ImgLoaderHints.LOAD_COMPLETELY</span>. This is used in certain places in SPIM_Registration to tell BDV’s hdf5 ImgLoader that it should read the full image completely in one go (because this is faster than using a cached image when we already know that we will need to access every single pixel of the image). Of course, hints are just hints, and most ImgLoaders will just ignore them.</div><div><br></div><div>ImgLoaders and SetupImgLoaders have been put into an interface hierarchy:</div><div><img apple-inline="yes" id="4817C6BE-B115-495F-B7BE-9CF4EEF661ED" height="397" width="1262" apple-width="yes" apple-height="yes" src="cid:D4E65A0E-7E37-4CF3-8395-D2E2FDB2914B@mpi-cbg.de"></div><div>BasicSetupImgLoader can give a T image for every timepoint.</div><div>SetupImgLoader can additionally give a image converted to FloatType for every timepoint, and provide some metadata (this is required for SPIM_Reconstruction).</div><div>BasicMultiResolutionSetupImgLoader has multiple resolutions of every T image for every timepoint.</div><div>MultiResolutionSetupImgLoader provides both multi-resolution and float-converted data.</div><div>ViewerSetupImgLoader is multi-resolution and provides additionally Volatile versions of each image (this is implemented by most bdv cached images)</div><div><br></div><div>This hierarchy is paralleled by ImgLoaders:</div><div><img apple-inline="yes" id="0877E170-E66D-47B8-84DC-E77CDE63DBB9" height="363" width="832" apple-width="yes" apple-height="yes" src="cid:5217B90C-45E1-4FCE-BA4E-2F4533621980@mpi-cbg.de"></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><u>How can you fix your ImgLoader implementation?</u></div><div><br></div><div><div>I tried to make that easy. The basic idea is the following:</div><div>The old interface <font face="Monaco" style="font-size: 11px;">ImgLoader<T></font> (etc) is still available as <font face="Monaco" style="font-size: 11px;">LegacyImgLoader<T></font> (etc). You just use your old implementation and change "<font face="Monaco" style="font-size: 11px;">implements ImgLoader<T></font>" to "<font face="Monaco" style="font-size: 11px;">implements LegacyImgLoader<T></font>”.</div><div>There is a <font face="Monaco" style="font-size: 11px;">LegacyImgLoaderWrapper<T></font> (etc) class that you can extends to wrap your (old) implementation as a <span style="font-family: Monaco; font-size: 11px;">ImgLoader</span> conforming to the new API.</div></div><div>More detailed instructions below.</div><div><br></div><div>To test, get the “types” branch of projects</div><div><div><a href="https://github.com/bigdataviewer/spimdata">https://github.com/bigdataviewer/spimdata</a> and</div><div><a href="https://github.com/bigdataviewer/bigdataviewer-core">https://github.com/bigdataviewer/bigdataviewer-core</a></div></div><div>Add SNAPSHOT dependencies in your projects pom.xml:</div><div><div style="margin: 0px; font-size: 11px; font-family: Monaco; color: rgb(78, 145, 146);"><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #009193"><</span>dependency<span style="color: #009193">></span></div><div style="margin: 0px; font-size: 11px; font-family: Monaco; color: rgb(78, 145, 146);"><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #009193"><</span>groupId<span style="color: #009193">></span><span style="color: #000000">sc.fiji</span><span style="color: #009193"></</span>groupId<span style="color: #009193">></span></div><div style="margin: 0px; font-size: 11px; font-family: Monaco;"><span class="Apple-tab-span" style="white-space:pre"> </span><span style="color: #009193"><</span><span style="color: #4e9192">artifactId</span><span style="color: #009193">></span><span style="text-decoration: underline">bigdataviewer</span>-core<span style="color: #009193"></</span><span style="color: #4e9192">artifactId</span><span style="color: #009193">></span></div><div style="margin: 0px; font-size: 11px; font-family: Monaco;"><span class="Apple-tab-span" style="white-space:pre"> </span><span style="text-decoration: underline ; color: #009193"><</span><span style="text-decoration: underline ; color: #4e9192">version</span><span style="text-decoration: underline ; color: #009193">></span><span style="text-decoration: underline">1.2.3-SNAPSHOT</span><span style="text-decoration: underline ; color: #009193"></</span><span style="text-decoration: underline ; color: #4e9192">version</span><span style="text-decoration: underline ; color: #009193">></span></div><div style="margin: 0px; font-size: 11px; font-family: Monaco; color: rgb(78, 145, 146);"><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #009193"></</span>dependency<span style="color: #009193">></span></div><div style="margin: 0px; font-size: 11px; font-family: Monaco; color: rgb(78, 145, 146);"><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #009193"><</span>dependency<span style="color: #009193">></span></div><div style="margin: 0px; font-size: 11px; font-family: Monaco; color: rgb(78, 145, 146);"><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #009193"><</span>groupId<span style="color: #009193">></span><span style="color: #000000">sc.fiji</span><span style="color: #009193"></</span>groupId<span style="color: #009193">></span></div><div style="margin: 0px; font-size: 11px; font-family: Monaco; color: rgb(78, 145, 146);"><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #009193"><</span>artifactId<span style="color: #009193">></span><span style="color: #000000">spim_data</span><span style="color: #009193"></</span>artifactId<span style="color: #009193">></span></div><div style="margin: 0px; font-size: 11px; font-family: Monaco;"><span class="Apple-tab-span" style="white-space:pre"> </span><span style="text-decoration: underline ; color: #009193"><</span><span style="text-decoration: underline ; color: #4e9192">version</span><span style="text-decoration: underline ; color: #009193">></span><span style="text-decoration: underline">1.0.0-beta-8-SNAPSHOT</span><span style="text-decoration: underline ; color: #009193"></</span><span style="text-decoration: underline ; color: #4e9192">version</span><span style="text-decoration: underline ; color: #009193">></span></div><div style="margin: 0px; font-size: 11px; font-family: Monaco; color: rgb(78, 145, 146);"><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #009193"></</span>dependency<span style="color: #009193">></span></div></div><div style="margin: 0px;"><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;">and make the enforcer rules shut up about it:</div><div><div style="color: rgb(78, 145, 146); font-family: Monaco; font-size: 11px; margin: 0px;"><span style="color: #000000"><span class="Apple-tab-span" style="white-space:pre"> </span></span><span style="color: #009193"><</span>properties<span style="color: #009193">><</span>enforcer.skip<span style="color: #009193">></span><span style="color: #000000">true</span><span style="color: #009193"></</span>enforcer.skip<span style="color: #009193">></</span>properties<span style="color: #009193">></span></div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;">Now you should get compile errors...</div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;">Fix them as indicated above, and detailed in the following.</div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;"><br></div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;"><br></div><div><div><u>To adapt an "old" ImgLoader:</u></div><div><br></div><div>Assume for example OldImageLoader</div><div><br></div><div>1.) copy OldImageLoader to LegacyOldImageLoader</div><div><br></div><div>2.) in LegacyOldImageLoader: change implements ImgLoader<...> to implements LegacyImgLoader<...></div><div><br></div><div>3.) Let OldImageLoader extends LegacyImgLoaderWrapper.</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>For each public constructor, just call super( new LegacyOldImageLoader( ... constructor parameters ... )</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>Remove the rest of the code.</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>This satisfies all requirements of the ImgLoader interface. If you need to expose additional public API from your OldImageLoader, you can forward to the LegacyOldImageLoader which is available as member variable legacyImgLoader.</div><div><br></div><div><br></div><div><u>To adapt an "old" ViewerImgLoader:</u></div><div><br></div><div>For example CatmaidImageLoader</div><div><br></div><div>1.) copy CatmaidImageLoader to LegacyCatmaidImageLoader</div><div><br></div><div>2.) in LegacyCatmaidImageLoader:</div><div><br></div><div>2.1) change extends AbstractViewerImgLoader to extends AbstractLegacyViewerImgLoader:</div><div><br></div><div>import bdv.AbstractViewerImgLoader;</div><div>public class CatmaidImageLoader extends AbstractViewerImgLoader< ARGBType, VolatileARGBType ></div><div><br></div><div>import bdv.spimdata.legacy.AbstractLegacyViewerImgLoader;</div><div>public class LegacyCatmaidImageLoader extends AbstractLegacyViewerImgLoader< ARGBType, VolatileARGBType ></div><div><br></div><div>2.2) if you use VolatileGlobalCellCache in your ImgLoader:</div><div>VolatileGlobalCellCache no longer has generic parameters. The generic parameter moved to the per-image CellCache.</div><div>Also VolatileGlobalCellCache is no longer constructed with an CacheArrayLoader. This also moved to the per-image CellCache.</div><div>-> Remove generics from VolatileGlobalCellCache</div><div>-> Add generic parameter to per-image CellCache</div><div>-> remove CacheArrayLoader parameter fron VolatileGlobalCellCache constructor. Instead, store your CacheArrayLoader into a member variable and use it to construct per-image CellCache.</div><div><br></div><div>Here are all the lines that needed to be changed in LegacyCatmaidImageLoader:</div><div><br></div><div><span class="Apple-tab-span" style="white-space:pre"> </span>private final VolatileGlobalCellCache< VolatileIntArray > cache;</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>...</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>cache = new VolatileGlobalCellCache< VolatileIntArray >(</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>new CatmaidVolatileIntArrayLoader( urlFormat, tileWidth, tileHeight, zScales ), 1, 1, numScales, 10 );</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>...</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>final CellCache< VolatileIntArray > c = cache.new VolatileCellCache< VolatileIntArray >( view.getTimePointId(), view.getViewSetupId(), level, cacheHints, loader );</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>...</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>public VolatileGlobalCellCache< VolatileIntArray > getCache()</div><div><br></div><div>And here is what they changed to:</div><div><br></div><div><span class="Apple-tab-span" style="white-space:pre"> </span>private final VolatileGlobalCellCache cache;</div><div><br></div><div><span class="Apple-tab-span" style="white-space:pre"> </span>private final CatmaidVolatileIntArrayLoader loader;</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>...</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>cache = new VolatileGlobalCellCache( 1, 1, numScales, 10 );</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>loader = new CatmaidVolatileIntArrayLoader( urlFormat, tileWidth, tileHeight, zScales );</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>...</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>final CellCache< VolatileIntArray > c = cache.new VolatileCellCache< VolatileIntArray >( view.getTimePointId(), view.getViewSetupId(), level, cacheHints, loader );</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>...</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>public VolatileGlobalCellCache getCache()</div><div><br></div><div>3.) Let CatmaidImageLoader extend LegacyViewerImgLoaderWrapper< ARGBType, VolatileARGBType, LegacyCatmaidImageLoader ></div><div><span class="Apple-tab-span" style="white-space:pre"> </span>For each public constructor, just call super( new LegacyCatmaidImageLoader( ... constructor parameters ... )</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>Remove the rest of the code.</div><div><br></div><div><span class="Apple-tab-span" style="white-space:pre"> </span>The full CatmaidImageLoader looks like this:</div><div><br></div><div>package bdv.img.catmaid;</div><div><br></div><div>import net.imglib2.type.numeric.ARGBType;</div><div>import net.imglib2.type.volatiles.VolatileARGBType;</div><div>import bdv.spimdata.legacy.LegacyViewerImgLoaderWrapper;</div><div><br></div><div>public class CatmaidImageLoader extends LegacyViewerImgLoaderWrapper< ARGBType, VolatileARGBType, LegacyCatmaidImageLoader ></div><div>{</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>public CatmaidImageLoader(</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>final long width,</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>final long height,</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>final long depth,</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>final double zScale,</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>final int numScales,</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>final String urlFormat,</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>final int tileWidth,</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>final int tileHeight )</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>{</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>super( new LegacyCatmaidImageLoader( width, height, depth, zScale, numScales, urlFormat, tileWidth, tileHeight ) );</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>}</div><div>}</div></div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;"><br></div></div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;"><br></div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;"><br></div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;"><br></div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;"><br></div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;"><br></div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;">It would be cool if you could update your ImgLoaders as soon as possible. If there are any problems I’ll be happy to help. If your project is on github, I can also just fix it for you. Just let me know!</div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;">I plan to merge the types branches of the above mentioned projects into the respective masters and release artifacts next Monday (5. October), and unless there are objections I would upload to Fiji updater next Friday (9. October).</div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;"><br></div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;">best regards,</div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;">Tobias</div><div style="color: rgb(0, 0, 0); font-family: Helvetica; font-size: 12px;"><br></div></div></body></html>