GUI quickstart#

This walkthrough takes the bundled CT phantom from preprocessing to a radiomics CSV file. Install Z-Rad using Installation, then open the packaged application or run python main.py from the repository root in your Python environment.

Z-Rad graphical interface

Z-Rad main window.#

The application has four tabs: Preprocessing, Filtering, Radiomics, and Visualization. Each tab reads files from its selected input directory. After a processing step, select its output directory as the input for the next step.

Prepare the dataset#

Use the bundled CT phantom for a first run. The steps below use one case and fixed demonstration settings; choose settings for your own study separately. No Python installation is needed if you use the packaged application.

  1. Download ibsi_ct_radiomics_phantom.zip from the repository’s phantom archive page using the download button. If you already have a source checkout, use the same archive in tests/data/.

  2. Extract the ZIP and open ibsi_ct_radiomics_phantom/nifti.

  3. Create a working folder named study with an input/case_01 subfolder. Copy image/phantom.nii.gz into that case folder. Copy mask/mask.nii.gz there too and rename it to GTV-1.nii.gz. Keep the .nii.gz files compressed.

The resulting layout is:

study/
└── input/
    └── case_01/
        ├── phantom.nii.gz
        └── GTV-1.nii.gz

See the dataset attribution and license terms before reusing or redistributing the phantom. Enter NIfTI names in the GUI without .nii or .nii.gz. For DICOM input and datasets with multiple cases, see Expected data structure.

Preprocess the images and masks#

  1. Open Preprocessing and select study/input as Input Directory.

  2. Set Output Directory to study/preprocessed. Leave the folder-range and folder-list fields empty to process every case.

  3. Select CT and NIfTI, enter phantom as NIfTI Image and GTV-1 as NIfTI Masks.

  4. Set Threads to 1, Resample Resolution to 2 mm, and Resample Dimension to 3D. Select Linear for both image and mask interpolation and set the mask interpolation threshold to 0.5. Leave Mask Union unchecked.

  5. Save these preprocessing settings with File -> Save Input or Ctrl+S to a file named preprocessing.json in study. Click RUN and wait for the completion message. Check the run log for one processed case, zero skipped cases, and zero failed cases. See Troubleshooting for log locations.

For each processed case, the output contains image.nii.gz and GTV-1.nii.gz. Open study/preprocessed in GUI visualization and inspect the image and mask alignment before extraction.

Extract features#

  1. Open Radiomics. Select study/preprocessed as Input Directory and study/results as Output Directory.

  2. Select CT and NIfTI. Enter image as NIfTI Image and GTV-1 as NIfTI Masks. Leave NIfTI Filtered Image empty for this workflow.

  3. Set Threads to 1 and leave the folder-range and folder-list fields empty. Select 3D, averaged and Number of Bins, then enter 32. Leave Intensity Range and Outlier Removal unchecked.

  4. Save the radiomics settings to a separate radiomics.json file in study with File -> Save Input or Ctrl+S, then click RUN.

  5. Open study/results/radiomics.csv. It should contain one data row with pat_id equal to case_01, mask_id equal to GTV-1, and stat_mean approximately -48.93 HU. The no_bins value is 31: it counts occupied grey levels, which can be fewer than the requested 32. See Understanding results for column definitions and Troubleshooting if the row is missing.

Keep both saved configurations and the logs with the results. This mean differs from the Python API quickstart because this workflow resamples the image and mask first. For your own studies, use Feature extraction concepts to choose aggregation and Discretization guidelines to choose bin settings.

Add filtering when needed#

To extract features from a filtered image, run GUI filtering after preprocessing. Select study/preprocessed as input, enter image as the NIfTI image name, and save the filtered output to study/filtered.

Filtering writes a filtered image into each case folder; it does not copy the original image or masks. Copy each filtered image into the matching case folder under study/preprocessed so extraction can read all three files together:

study/preprocessed/case_01/
├── image.nii.gz
├── GTV-1.nii.gz
└── <filter-output-name>.nii.gz

In Radiomics, keep NIfTI Image set to image and enter the actual filtered filename, without the extension, in NIfTI Filtered Image. Use a separate results directory to keep this extraction distinct from the unfiltered run.