4d — Export 4D-STEM images for cryoSPARC

Export 4D-STEM images for cryoSPARC processing

This script (export/standard/10_ExportImages.script) collects the reconstructed images from every dataset in the project and writes them, together with their metadata, into a folder structure compatible with cryoSPARC's Import Movies function. Images are exported as MRC files and the per-image metadata is written into a STAR file, so 4D-STEM reconstructions can be taken straight into cryoSPARC for further single-particle processing. It is the Export section's main hand-off step.

Purpose

For each image directory in the project it copies the chosen reconstruction outputs (bright-field, dark-field, parallax, shadow, ptychography) into a tidy, per-type folder layout under one export directory, renaming each file after its original micrograph, and builds a metadata STAR file listing every exported image with its voltage, aberration, defocus and dose.

Parameters

Parameter	Role
`export_doit`	Master switch. `y` actually performs the export; `n` only simulates it (a dry run that reports what would be copied).
`export_basedir`	The directory the export is written into (created if missing).
`export_h5file_doit`	Also copy the raw HDF5 stack of each dataset into an `HDF5_Stacks/` subdirectory.
`export_reconstruction_brightfield`	Export the bright-field image (`fd_BF_image.mrc`).
`export_reconstruction_darkfield`	Export the dark-field image (`fd_DF_image.mrc`).
`export_reconstruction_parallax_py4dstem`	Export the py4DSTEM parallax reconstruction (`parallax_output_upsampled.mrc`).
`export_reconstruction_parallax_torchslice`	Export the Torchslice parallax reconstruction (`parallax.mrc`).
`export_reconstruction_shadow`	Export the shadow image (`shadow_image.mrc`).
`export_reconstruction_ptycho_py4dstem`	Export the py4DSTEM ptychography result.
`export_reconstruction_ptycho_ptychobones`	Export the PtychoBones ptychography result.
`export_reconstruction_ptycho_torchslice`	Export the Torchslice ptychography result.
`export_metadata_doit`	Write the `micrographs_4d.star` metadata file (voltage, C_s, defocus, doses per image).

Each reconstruction toggle is a y/n switch — turn on only the reconstruction types you actually produced. With export_doit = n the whole run is a simulation, handy for checking the file mapping before copying anything.

Algorithm

Ensures export_basedir exists and creates the HDF5_Stacks/ subdirectory; if metadata export is on, removes any previous micrographs_4d.star.
Reads the project's list of image directories (4d_merge_dirfile.dat) and loops over each. For every dataset it fetches the per-image parameters from the central project database (merge/4d_project.db): the raw-stack name, KV, CS, the parallax defocus, and the frame/total dose (missing values default to 0). The output file names are derived from the original micrograph name.

For each enabled reconstruction type it calls the helper 4d_export_files.com, which copies that dataset's MRC file into a per-type subfolder of the export directory, renamed with a short prefix:

Type	Source	Exported as
Bright-field	`fd_BF_image.mrc`	`brightfield/BF_<name>.mrc`
Dark-field	`fd_DF_image.mrc`	`darkfield/DF_<name>.mrc`
Parallax (py4DSTEM)	`parallax_output_upsampled.mrc`	`parallax/ParPy_<name>.mrc`
Parallax (Torchslice)	`parallax.mrc`	`parallax/ParTo_<name>.mrc`
Shadow	`shadow_image.mrc`	`shadow/Shad_<name>.mrc`
Ptychography (py4DSTEM)	`ptycho_py4dstem.mrc`	`ptycho_py4dstem/PtyPy_<name>.mrc`
Ptychography (PtychoBones)	`ptycho_ptychobones.mrc`	`ptycho_ptychobones/PtyBo_<name>.mrc`
Ptychography (Torchslice)	`ptycho_torchslice.mrc`	`ptycho_torchslice/PtyTo_<name>.mrc`

The raw HDF5 stack is likewise copied into HDF5_Stacks/ when that toggle is on.

If metadata export is on, it appends one row per image to micrographs_4d.star — columns _rln4dscanName, _rlnImage, _rlnVoltage, _rlnSphericalAberration, _rlnDefocus, _rlnFrameDose, _rlnTotalDose — writing the header first if the file is new.
Reports progress and prints the full export path when finished.

Results

Data written — a cryoSPARC-ready folder under export_basedir:

One subdirectory per exported reconstruction type (brightfield/, darkfield/, parallax/, shadow/, ptycho_*/), each holding the MRC images renamed after their original micrograph.
HDF5_Stacks/ — the raw HDF5 stacks (when export_h5file_doit is on).
micrographs_4d.star — the per-image metadata table (when export_metadata_doit is on).

The export directory and the STAR file are registered as important results, so they show in the Manual Processing Results / Images panel. In cryoSPARC, use Import Movies (or Import Micrographs) pointing at the exported MRC folder and micrographs_4d.star to continue processing.