Zarr tools on khlabgpu1 (make-zarr and crop-zarr)

Two guided commands on our GPU server, khlabgpu1, that prepare image data for PyReconstruct. They ask a few questions, then work in the background, so your own computer is free and the job keeps going if you close the window or lose the VPN. A 284-image series (160 GB) that a laptop estimated at more than 10 hours was ready to use on khlabgpu1 in about 50 minutes.

🧱 `make-zarr`

Turns a folder of section images into a PyReconstruct zarr, with all of its scale levels, plus a one-file .tar copy for moving it.

Open the make-zarr guide →

✂️ `crop-zarr`

Makes a copy of a series' zarr that keeps only the area around one object and blacks out the rest. The images keep their size, so it still lines up with the series.

Open the crop-zarr guide →

1 Before you start
2 How the tools work
3 What you get
4 Copying a zarr somewhere else
5 What's new
6 Troubleshooting

Before you start

Get an account on khlabgpu1. Ask Dusten.
Off campus or on wifi, connect to the UT VPN (Cisco AnyConnect) first.
Open a terminal on khlabgpu1, either way:
- From your own computer (Mac: Terminal; Windows: PowerShell):
  ssh <your khlabgpu1 username>@khlabgpu1.cns.utexas.edu
- Or open a Terminal in your remote desktop session on khlabgpu1.

Where your data can be. khlabgpu1 has its own drives (/data/data5, /data/data6), and it also sees khlabfiles' data under /data/data1/... (for example /data/data1/public/Teams/...). Reading from khlabfiles is fine. Writing a zarr onto khlabfiles is slow (a zarr is thousands of small files), so the tools suggest your own folder on khlabgpu1, /data/data6/<your username>. To put the result on khlabfiles afterwards, see Copying to khlabfiles.

How the tools work

Type make-zarr or crop-zarr and press Enter.
Answer the questions. Press Tab to autocomplete a folder, file or object name. A second Tab press shows you options inside the directory to help you traverse. You can paste a path. Type q to quit.
Check the Ready box, then answer y.
A live screen shows progress and the time left.
To check on it later, run the same command again. It lists your jobs; type a job's number to open it.

You can close the window or lose the VPN at any time. The job keeps running on khlabgpu1.

Run the command again to see your jobs. Type a number to open one.

Key	Where	What it does

Key	Where	What it does
`q`	progress screen	Go back to the job list. The job keeps running.
`s`	progress screen	Stop the job (it asks first). You can continue it later.
`r`	a stopped or failed job	Try again. It continues from the step that stopped.
`d`	a stopped or failed job	Delete its half-done copy on khlabgpu1's fast disk (shown only when there is one).
`c`	a finished job	Copy it somewhere else, with step-by-step help.

What you get

Next to the finished zarr (for a crop, <name> is the crop's name):

File	What it is

File	What it is
`<name>-zarr`	The zarr folder. In PyReconstruct: Series > Images > Find/change image directory, then pick this folder.
`<name>-zarr.tar`	The same zarr packed into one file. One file copies much faster over the network or to an external drive.
`<name>-zarr.tar.HOW-TO-COPY.txt`	Step-by-step copy instructions for Mac and Windows, including external drives.
`<name>-zarr.RUN-LOG.txt`	Who ran the job and when, the input and output, each step's time, every attempt, and the full log. It updates at every step while the job runs. Send it to Dusten if you need help.

Copying a zarr somewhere else

On a finished job, press c:

1 — a folder on khlabfiles. It copies the one-file .tar there in the background, then shows the three lines that unpack it on khlabfiles itself. See Copying to khlabfiles.
2 — another folder on khlabgpu1. It copies the zarr in the background, with a progress bar, and continues where it left off if stopped.
3 — your own computer, or an external drive plugged into it. It asks Windows or Mac, and folder or drive, then shows exactly what to type. See Copying to your own computer.

Copying to khlabfiles

Copy the one-file .tar to khlabfiles, then unpack it on khlabfiles itself. The paths are the same on both servers: a folder you see on khlabgpu1 as /data/data1/... is /data/data1/... on khlabfiles too.

Copy the .tar. On the finished job, press c, then 1, and pick the khlabfiles folder. It copies in the background with a progress bar. By hand on khlabgpu1, it is the same as:
cp /data/data6/<your username>/NAME-zarr.tar /data/data1/<folder on khlabfiles>/
Log in to khlabfiles with your UT EID and unpack it there. When the copy is done, the screen shows these lines with your folder filled in:
ssh <your EID>@khlabfiles.clm.utexas.edu cd /data/data1/<folder on khlabfiles> tar -xf NAME-zarr.tar
Check it opens in PyReconstruct (Series > Images > Find/change image directory), then you can delete the .tar there with rm NAME-zarr.tar. The copy on khlabgpu1 stays as a backup.

Do not unpack into a khlabfiles folder from khlabgpu1, and do not use c → 2 for a khlabfiles folder. Both write the zarr's files one at a time over the network, and each waits for khlabfiles to confirm it. If you cannot log in to khlabfiles, ask Dusten.

Measured on Oct 6, 2026, with a 4.5 GB zarr of about 124,000 files:

Step	Time

Step	Time
DO copy the `.tar` from khlabgpu1 to khlabfiles	75 s
DO unpack it on khlabfiles itself	29 s
AVOID unpack it into khlabfiles from khlabgpu1	about 4 h (12% done after 29 min)

Copying to your own computer or an external drive

The copy guide for a Windows computer and an external drive

The copy guide, here for a Windows computer and an external drive.

The short version, run on your own computer (not on khlabgpu1), with the UT VPN on:

Mac

cd ~/Desktop
rsync -av --partial --progress <you>@khlabgpu1.cns.utexas.edu:'/path/to/NAME-zarr.tar' .
tar -xf NAME-zarr.tar

Windows (PowerShell)

cd ~\Desktop
scp <you>@khlabgpu1.cns.utexas.edu:"/path/to/NAME-zarr.tar" .
tar -xf NAME-zarr.tar

External drives must be exFAT, NTFS or APFS. A FAT32 drive cannot hold a file over 4 GB.
A big copy over the VPN can take hours. Keep your computer plugged in and set it not to sleep.
If a copy stops: on a Mac, run the same rsync again; it continues. On Windows, continue with sftp <you>@khlabgpu1.cns.utexas.edu, then reget "/path/to/NAME-zarr.tar" "NAME-zarr.tar", then exit.
You need room for the .tar and the unpacked zarr while you unpack. Delete the .tar afterwards to get half of it back.

What's new

Newest first. The tools on khlabgpu1 update for everyone at once; you do not need to install anything.

Date	Tool	What changed

Date	Tool	What changed
Oct 10, 2026 (v5)	make-zarr, crop-zarr	The tools now update themselves every night, so everyone always runs the newest version. Every crop's `crop_log.txt` now starts with a `Tool:` line that says which version of crop-zarr made it.
Oct 9, 2026 (v4)	crop-zarr	Sections without the crop object are no longer black. Each rescued section keeps its original EM image, now cropped using the same crop window from the adjacent sections, so you can follow the area above and below it. A true known missing section in a zarr, or one stored all black, gets a mid-gray level square there instead. A crop that would keep nothing stops before it writes anything. Every crop now has a `crop_log.txt` inside it that says what was done, section by section, and the Done screen shows its summary.
Oct 6, 2026 (v3)	make-zarr, crop-zarr	The copy menu (`c`) lists khlabfiles first. It copies the one-file `.tar` there and shows the three lines that unpack it. See Copying to khlabfiles.
Oct 6, 2026 (v2)	crop-zarr	Much faster. It skips the blacked-out parts when it writes. A test crop went from 12 min to under 2 min, and from 122,551 files to 10,080. The pixels are exactly the same.
Oct 6, 2026 (v1)	make-zarr, crop-zarr	First version on khlabgpu1, with a `.tar` copy and a `RUN-LOG.txt` next to every output.

Troubleshooting

You see	Do this

You see	Do this
"command not found" or "No such file or directory" when you type the command	Log out and back in, or type `hash -r`, then try again.
"You don't have permission to write in that folder"	Pick a folder you own, for example `/data/data6/<your username>`.
"That folder is on khlabfiles ... can take hours"	Answer `n` and pick `/data/data6/<your username>`. To put the result on khlabfiles afterwards, see Copying to khlabfiles.
"Not enough free space"	Pick a folder on a drive with more room, or ask Dusten.
A job failed	Open it from the list to see where it stopped, press `r` to try again, and send the `RUN-LOG.txt` to Dusten if it fails again.