How to use
This page walks through the recommended workflow for processing a folder of images with Quadrant Folding (QF), then describes the secondary features and the headless mode.
Workflow at a glance
Step 1 — Open an image or folder
Use File > Select an Image… (Ctrl+I) and pick any TIF/CBF/HDF5 file. QF loads the file, discovers all sibling images in that directory, and immediately processes the selected image with the default settings.
Once a folder is loaded, use the navigation arrows on the bottom strip to move through images:
< / > — previous / next image
<<< / >>> — previous / next HDF5 file (only for HDF5 input)
Process Current Folder — reprocess every image in the folder with the current settings
Process Current H5 File / Process All H5 Files — same for HDF5 frames
Already-processed images are reloaded from the cache rather than reprocessed, so navigation is fast. To force reprocessing, click Process Current Folder or delete the qf_cache folder under the output directory.
Step 2 — Choose an output directory
By default QF writes qf_results/, qf_cache/, and CSV files into the same folder as the input images. If the input directory is read-only, or you want to keep input and output separate, use File > Change Output Directory… before processing.
The output directory applies to:
qf_results/<name>_folded.tif— the folded imageqf_results/bg/<name>.bg.tif— the estimated background (when subtraction is on)summary.csv,summary2.csv,failedcases.txt— batch summariesqf_cache/— processing fingerprints used for fast reload
Step 3 — Set center and rotation on a reference image
Pick a clean, well-aligned frame as your reference. The right-hand panel Center and Set Rotation Angle groups contain everything needed.
Center tools
Button |
When to use |
|---|---|
Quick Center and Rotation Angle |
Auto-detect both center and rotation from the diffraction pattern. Good first attempt. |
Set Center by Chords |
Click 3 points on a strong ring; the center is fitted from the perpendicular bisectors of the chords. |
Set Center by Perpendiculars |
Draw two perpendicular lines through pairs of symmetric reflections. |
Set Center by Calibration |
Use a calibrant ring to derive both center and pixel-to-nm scale. |
Set Center Manually |
Click a single pixel to use as the center. Fast but least accurate. |
Apply Center |
Copy the current center to a chosen scope (this image / next N / whole folder). |
Restore Auto Center |
Discard the manual center and revert to auto-detection. |
Rotation tools
Button |
When to use |
|---|---|
Set Auto Orientation |
Open a dialog to pick the rotation-detection algorithm and whether to use Mode Orientation (use the most common angle across the folder). |
Set Angle Interactively |
Click two points to define the meridional axis. |
Set Angle Manually |
Type the angle in degrees. |
Apply Rotation |
Copy the current angle to a chosen scope. |
Restore Auto Rotation |
Revert to auto-detected angle. |
For full details on all shared tools (Double Zoom, fingerprinting, calibration dialog), see Common Settings — Diffraction Center and Rotation.
Once the reference image looks right, use Apply Center and Apply Rotation (scope = whole folder) to propagate the values to every image.
Step 4 — Detect alignment across the folder
After propagating, most images will be correctly aligned, but some may have shifted center or rotation and need individual correction. Open Tools > Detect Image Alignment… (Ctrl+D) to identify outliers.
The dialog shows one row per image with columns for:
Original Center and Auto Center (with the distance between them)
Rotation and Auto Rotation (with the difference)
Center Mode / Rotation Mode — whether the values were set manually or auto-detected
Dist from Base / Rot Diff from Base — how far each image is from the chosen base image
Size and Image Difference — pixel-difference between this image and the base
Fold Std (sum) and Fold Std (norm) — fold-symmetry scores when Run symmetry test on detection is enabled (lower = more symmetric)
Click Run Detection to populate the columns. Sort by any column to surface outliers — for example, sort by Auto Center Difference to find images where the auto-detected center disagrees with the manually-applied one, or by Fold Std (norm) to find images that fold poorly.
The dialog is non-modal: leave it open and switch between it and the main window freely. Changes you make in the main window update the table automatically.
Step 5 — Fix individual misaligned images
For each outlier in the alignment table:
Click the row — the main window navigates to that image.
Adjust center / rotation using the Step 3 tools on the main window.
The table row updates as soon as you change the values.
Right-clicking a row offers:
Set Center and Rotation — switches focus to the main window with a hint dialog.
Set Global Base — promote this image as the reference for the
Dist from Basecolumns.Ignore — exclude this image from subsequent batch operations.
Repeat until all images are within an acceptable tolerance.
Step 6 — Inspect the result and switch display modes
Switch to the Results tab to see the folded, background-subtracted output. The display panel on the right has a Show dropdown that switches between several views without reprocessing:
Mode |
What it shows |
|---|---|
Subtracted |
Final result: average fold with background removed, mirrored to full 2D pattern. This is the default. |
Background |
The estimated background image. Useful for sanity-checking the subtraction. |
Folded |
The plain average fold without background subtraction. |
Evaluation Mask |
The composite mask used by the background optimizer (R-min/R-max annulus, equator band, peak/beam exclusions, layer lines). |
Synthetic Signal |
The synthetic Gaussian-blob grid added to the fold during optimizer scoring. |
Synthetic Mask |
The mask region of the synthetic data. |
Other Results-tab controls:
Rotate 90 degree — rotate the displayed result by 90° (also rotates the saved tif).
Show Quadrant Separator — draw the horizontal/vertical lines separating the four mirrored quadrants.
Set Region Of Interest (ROI) — drag a rectangle on the result to crop the output. The ROI is symmetric about the center.
Unset ROI — remove the ROI.
Persist ROI size — keep the same W/H ROI when moving to the next image.
Persist intensity — keep the min/max intensity range across images.
Step 7 — Configure background subtraction (optional)
Background subtraction is not required for quadrant folding itself. If you only need the folded image (higher signal-to-noise, no diffuse background removed), leave the method as None and skip to Step 8. Use this step when you want to remove the diffuse muscle background before saving or downstream analysis.
The Background Subtraction group on the right panel is the central control. It has two entry points:
Quick path — Apply Default Optimization
Click the blue Apply Default Optimization button. QF runs the automated optimizer on the current image using the default method set and writes the chosen method and parameters back to the Current Configuration display. This is the recommended first step on a new dataset.
Custom path — Advanced Configuration
Click Advanced Configuration to open the full Background Subtraction dialog. The dialog is organised as three steps:
Step 1 — Adjust Image Setting and Process
R-min/R-max group — see and override the automatic values; Manual R-min/max lets you click on the image; Persist R-min/max keeps the same values across images.
Image Processing group — Downsample (speeds up the optimizer) and Smooth Image (guided-filter pre-smoothing).
Subtraction group — pick Processing Mode:
Manual — choose one of the six methods (
2D Convexhull,Circularly-symmetric,White-top-hats,Roving Window,Smoothed-Gaussian,Smoothed-BoxCar) and tune its parameters by hand. See the Methods Reference below.Automated — pick which methods to try, the step schedule, max iterations, and an early-stop loss threshold.
Optimization Target and Evaluation Settings group — configure the evaluation mask (equator height, equator centre radius, layer-line spacing, layer-line width), the loss metric weights, and the synthetic-signal parameters.
Apply Selected Subtraction Settings — run the subtraction with these settings.
Step 2 — Review Results
After applying, the Results panel inside the dialog shows the Loss value and a per-metric breakdown table (MSE, oversubtraction share, non-baseline share, negative-connected share, smoothness — each shown as raw, normalized, and weighted contribution). Tick Save result metrics to csv to also write these into qf_results/bg/background_metrics.csv.
Step 3 — Adjust Batch Processing Settings and Launch
Configurations table — save the current method+parameters as a named configuration. You can build up several configurations (e.g. one for low-angle, one for high-angle) and apply them to different images.
Choose best configuration for images automatically — for each image, pick whichever saved configuration scores the lowest loss.
Automatically create new configurations for outlier images — when an image scores poorly with all existing configurations, derive a new one for it.
Manually assign configurations to images — open a per-image picker.
Process Current Folder — run the batch with these settings.
Transition mode
If a single method does not work well across all radii, switch the right-panel Options dropdown to Manual Setting | Transition. Two method choices and parameter sets appear; configure each independently and set:
Transition radius — where the two backgrounds are blended (typical guideline: just outside the M3 meridional peak).
Transition delta — width of the linear blend region.
See How it works — Step 9 for the algorithmic detail.
Step 8 — Process the whole folder and collect output files
When the settings look right on representative images, click Process Current Folder (either the navigation button or the one inside the Background Subtraction dialog). QF writes the following under the output directory:
qf_results/
File |
Description |
|---|---|
|
The folded, background-subtracted result image (32-bit float TIFF). When Save Compressed Image is checked, written as |
|
One row per processed image. Key columns: |
|
Same data, transposed for easier spreadsheet analysis. |
|
Images that could not be processed automatically (no peaks, fitting failed, high error, or manually rejected). |
qf_results/bg/
Written when a background-subtraction method other than None is active.
File |
Description |
|---|---|
|
The estimated background image (32-bit float TIFF). |
|
|
|
Per-image raw and normalized evaluation metrics with their weights and running means. Written only when Save result metrics to csv is enabled. |
For the meaning of loss, bgSum, and symmetry, see How it works — Step 11.
Methods Reference
These six methods are available in the Background Subtraction dialog. The algorithms are described in detail in How it works — Step 8. Here is the parameter cheat-sheet:
Method |
Key parameters |
|---|---|
Circularly-symmetric |
Pixel range %, radial bin size, smoothing factor |
2D Convexhull |
R-min, angle bin (default 1°) |
Roving Window |
R-min, window size (X/Y), pixel range %, smoothing, tension |
White-top-hats |
Top-hat disk size |
Smoothed-Gaussian |
R-min, number of cycles, Gaussian FWHM |
Smoothed-BoxCar |
R-min, number of cycles, box car size (X/Y) |
In Transition mode each method has a separate outer-parameter set (suffix _out in the JSON).
Other features
Right-click — Ignore a quadrant
Right-click on any quadrant in the Original Image tab and choose Ignore This Quadrant. The selected quadrant is excluded from the averaging step (useful when one quadrant has a detector defect or shadow). Use Unignore This Quadrant to re-include it.
Save and load settings
File > Save Current Settings (
Ctrl+S) — write current parameters toqfsettings.json. Per-image state (center, rotation, ROI per image) is not included.File > Load Settings… (
Ctrl+Shift+S) — load a settings file and reprocess.
Fold Image checkbox
Unchecking Fold Image processes the original (unfolded) image as if it were already folded. Useful when the input is already a quadrant-folded result from a previous run.
Headless Mode
For batch processing without a GUI, run from the terminal:
musclex qf -h -i <file.tif> [-s qfsettings.json] [-d]
musclex qf -h -f <folder> [-s qfsettings.json] [-d]
Arguments:
-i <file>— process a single file.-f <folder>— process every image in the folder.-s <settings.json>— load a settings file (generated by File > Save Current Settings in the GUI). Without this, defaults are used.-d— delete the existing cache before processing.
.. note:: On Windows, replace ``musclex`` with ``musclex-main.exe`` (typically under ``C:\Program Files\BioCAT\MuscleX\musclex``).
Multiprocessing
The headless runner processes one image per CPU core. Output for each worker is prefixed with the process index so interleaved log lines can be untangled.
qfsettings.json reference
A representative settings file. Names ending in _out are the outer-radius counterparts used in Transition mode. For the full set of accepted keys, see musclex/modules/QuadrantFolder.py.
{
"fix_center": true,
"center_x": 1024,
"center_y": 1024,
"rotation": 0,
"roi_w": 2048, "roi_h": 2048,
"downsample": 2,
"smooth_image": true,
"bg_options": 0,
"bgsub": "Circularly-symmetric",
"fixed_rmin": 100,
"fixed_rmax": 900,
"degree": 1,
"radial_bin": 1,
"cirmin": 10, "cirmax": 100,
"smooth": 1,
"tension": 1,
"win_size_x": 11, "win_size_y": 11,
"fwhm": 20,
"boxcar_x": 20, "boxcar_y": 15,
"cycles": 1,
"bgsub_out": "None",
"deg2": 1,
"smooth2": 1,
"tension2": 1,
"win_size_x_out": 11, "win_size_y_out": 11,
"fwhm_out": 20,
"boxcar_x_out": 20, "boxcar_y_out": 15,
"cycles_out": 1,
"transition_radius": 730,
"transition_delta": 60,
"optimize": false,
"methods": ["Circularly-symmetric", "2D Convexhull"],
"max_iterations": 200,
"early_stop": 0.005,
"equator_mask_height": 60,
"equator_center_beam_width": 20,
"m1": 50,
"layer_line_width": 8,
"freq": "medium"
}
bg_options:0= single method,1= Transition (usesbgsub_outoutsidetransition_radius).optimize: when true, ignoresbgsuband runs the automated optimizer overmethods.mask_thresis no longer user-configurable; invalid pixels are detected at the value −1 set by the empty-cell-and-mask preprocessing stage.