Package: imagej-rolling-ball
imagej-rolling-ballPython wrapper forImageJ's rolling ball background
subtractionusingpyimagej.InstallFollowpyimagej's installation
instructionInstallimagej-rolling-ballfrom pypipython-mpipinstallimagej-rolling-ballTo work with large images,daskandzarrwere used in the package. You
can install them yourself or specify the[large]installpython-mpipinstallimagej-rolling-ball[large]To work with pyramidal ome-tiff images,palomwas used. Install the[wsi]extraspython-mpipinstallimagej-rolling-ball[wsi]UsageThe key parameter is the rolling ball radius, according to thedoc, the radiusshould be at least as large as the radius of the largest object in the image
that is not part of the backgroundNOTE:While the java classBackgroundSubtracterhandles RGB image, the
current wrapper methods only accepts 2D arrays. One can process each channel
separately and combine all the processed channels usingnumpy.arrayornumpy.dstackBasic usageimportimagej_rolling_ballimportnumpybg_subtracter=imagej_rolling_ball.BackgroundSubtracter(java_options='-Xmx1g')img=numpy.eye(5)+1print('img\n',img,'\n')print('radius=1')print(bg_subtracter.rolling_ball_background(img,1),'\n')print('radius=2.5')print(bg_subtracter.rolling_ball_background(img,2.5),'\n')And the output of the above script should beimg[[2.1.1.1.1.][1.2.1.1.1.][1.1.2.1.1.][1.1.1.2.1.][1.1.1.1.2.]]radius=1[[0.0.0.0.0.][0.0.0.0.0.][0.0.0.0.0.][0.0.0.0.0.][0.0.0.0.0.]]radius=2[[0.0.0.0.0.][0.0.79128790.0.0.][0.0.0.79128790.0.][0.0.0.0.79128790.][0.0.0.0.0.]]Process large imageFor large array (e.g. array that contains more than 2,147,483,647 elements), theBackgroundSubtracter.rolling_ball_background_chunkedmethod is for such use
case. It returns adask.arrayby default or azarr.core.Arrayifcompute=Trueis set.In[1]:importimagej_rolling_ball...:importnumpy...:...:bg_subtracter=imagej_rolling_ball.BackgroundSubtracter(java_options='-Xmx4g')...:img=numpy.eye(10_000,dtype='uint8')+1ImageJVersion:2.14.0/1.54fIn[2]:bg_subtracter.rolling_ball_background_chunked(img,50,1024*5)Operatinginheadlessmode-theoriginalImageJwillhavelimitedfunctionality.Out[2]:dask.array<_trim,shape=(10000,10000),dtype=uint8,chunksize=(5120,5120),chunktype=numpy.ndarray>In[3]:bg_subtracter.rolling_ball_background_chunked(img,50,1024*5).compute()Out[3]:array([[1,0,0,...,0,0,0],[0,1,0,...,0,0,0],[0,0,1,...,0,0,0],...,[0,0,0,...,1,0,0],[0,0,0,...,0,1,0],[0,0,0,...,0,0,1]],dtype=uint8)In[4]:bg_subtracter.rolling_ball_background_chunked(img,50,1024*5,compute=True)Out[4]:<zarr.core.Array(10000,10000)uint8>Process chunked ome-tiff in command line interfaceUserolling-ballcommand to process multi-channel tiff file and write the
processed image to disk as a pyramidal ome-tiff.python -m pip install imagej-rolling-ball[wsi]is required.NAMErolling-ball

SYNOPSISrolling-ballIMG_PATHRADIUS<flags>

POSITIONALARGUMENTSIMG_PATHRADIUS

FLAGS--out_path=OUT_PATHType:Optional[str]Default:None-t,--target_chunk_size=TARGET_CHUNK_SIZEType:intDefault:5120--overwrite=OVERWRITEType:boolDefault:False-j,--java_options=JAVA_OPTIONSType:Optional[str]Default:None-i,--imagej_version=IMAGEJ_VERSIONType:Optional[str]Default:None-p,--pyramid_config=PYRAMID_CONFIGType:Optional[dict]Default:None--rolling_ball_kwargs=ROLLING_BALL_KWARGSType:Optional[dict]Default:None-n,--num_workers=NUM_WORKERSType:intDefault:4NOTES:To pass in JVM options, e.g. set max heap size (-Xmx4g), use the syntax of-j="-Xmx4g"The defaut Java heap size is 70% of the available memoryIncrease--num_workersmay speed up processing time, default is4The default output file will be generated next to the input file, the file
name ends with-ij_rolling_ball_{radius}.ome.tifExample commands:Minimal command, process file using rolling ball radius of100and
writebackground-subtracted image to diskrolling-ballpath/to/input/file.ome.tif100Write background image instead of subtracted image (--rolling_ball_kwargs "{'create_background': True}") to file; set JVM max heap size to 4 GB
(-j="-Xmx4g") and use 8 threads (-n=8)rolling-ballpath/to/input/file.ome.tif100\--out_pathpath/to/input/file-background_100.ome.tif\--rolling_ball_kwargs"{'create_background': True}"\-j="-Xmx4g"\--overwrite\-n=8Docker usageThe docker image can be build from the github repo or be pulled from the docker
hub.To process an image file (input.ome.tif) with rolling ball radius50in the
current directory:dockerrun-it--rm-v"$(pwd)":/data\yuanchen12/imagej-rolling-ball\rolling-ball/data/input.ome.tif50When the process is completed, output fileinput-ij_rolling_ball_50.ome.tifwill be generated.