### Full HistoQC Pipeline Configuration Example

Source: https://context7.com/choosehappy/histoqc/llms.txt

A comprehensive INI configuration file demonstrating the setup of a full HistoQC pipeline for H&E slides, including various modules and their parameters.

```ini
[pipeline]
steps= BasicModule.getBasicStats
    LightDarkModule.saveEqualisedImage
    ClassificationModule.byExampleWithFeatures:pen_markings
    ClassificationModule.byExampleWithFeatures:coverslip_edge
    LightDarkModule.minimumPixelIntensityNeighborhoodFiltering
    LightDarkModule.getIntensityThresholdPercent:darktissue
    BubbleRegionByRegion.detectSmoothness
    MorphologyModule.removeFatlikeTissue
    MorphologyModule.fillSmallHoles
    MorphologyModule.removeSmallObjects
    LocalTextureEstimationModule.estimateGreyComatrixFeatures:background
    BrightContrastModule.getContrast:background
    BrightContrastModule.getBrightnessGray:background
    BlurDetectionModule.identifyBlurryRegions
    BasicModule.finalProcessingSpur
    BasicModule.finalProcessingArea
    HistogramModule.compareToTemplates
    HistogramModule.getHistogram
    LocalTextureEstimationModule.estimateGreyComatrixFeatures:final
    BrightContrastModule.getContrast
    BrightContrastModule.getBrightnessGray
    BrightContrastModule.getBrightnessByChannelinColorSpace:RGB
    BrightContrastModule.getBrightnessByChannelinColorSpace:YUV
    DeconvolutionModule.separateStains
    SaveModule.saveFinalMask
    SaveModule.saveMacro
    SaveModule.saveThumbnails
    BasicModule.countTissuePieces
    BasicModule.finalComputations

[BaseImage.BaseImage]
image_work_size = 1.25x
in_memory_compression = True
mask_statistics = relative2mask

[BasicModule.getBasicStats]
image_work_size = 1.25x

[ClassificationModule.byExampleWithFeatures:pen_markings]
name: pen_markings
threshold: .5
examples: ./pen/1k_version/pen_green.png:./pen/1k_version/pen_green_mask.png
          ./pen/1k_version/pen_red.png:./pen/1k_version/pen_red_mask.png
          ./pen/1k_version/pen_black.png:./pen/1k_version/pen_black_mask.png
nsamples_per_example: 10000
area_threshold: 100
features:  frangi
           laplace
           rgb
frangi_scale_range: (1,10)
frangi_scale_step: 2
frangi_beta1: .5
frangi_beta2: 15
frangi_black_ridges: True
laplace_ksize: 3

[ClassificationModule.byExampleWithFeatures:coverslip_edge]
name: coverslip_edge
threshold: .5
examples: ./models/coverslip_edge_he/coverslip_edge.png:./models/coverslip_edge_he/coverslip_edge_mask.png
nsamples_per_example: 10000
area_threshold: 15
features:  frangi
           laplace
           rgb
dilate_kernel_size: 5

[LightDarkModule.minimumPixelIntensityNeighborhoodFiltering]
disk_size: 5
upper_threshold: 210
invert: True

[LightDarkModule.getIntensityThresholdPercent:darktissue]
name: dark
upper_threshold: .15
invert: true

[BubbleRegionByRegion.detectSmoothness]
threshold: .01
kernel_size: 10
min_object_size: 500

[MorphologyModule.removeFatlikeTissue]
kernel_size: 10
max_keep_size: 1000
fat_cell_size: 64

[MorphologyModule.fillSmallHoles]
min_size: 1000

[MorphologyModule.removeSmallObjects]
min_size: 64

[BlurDetectionModule.identifyBlurryRegions]
image_work_size = 2.5x
blur_radius: 100
blur_threshold: .15

[BasicModule.finalProcessingSpur]
disk_radius: 5

[BasicModule.finalProcessingArea]
area_threshold: 10000

[HistogramModule.compareToTemplates]
limit_to_mask: True
bins: 20
templates= ./templates/template1.png
           ./templates/template2.png
           ./templates/template3.png
           ./templates/template4.png

[HistogramModule.getHistogram]
limit_to_mask: True
bins: 20

[BrightContrastModule.getContrast]
limit_to_mask: True

[BrightContrastModule.getBrightnessGray]
limit_to_mask: True

[BrightContrastModule.getBrightnessByChannelinColorSpace:RGB]
limit_to_mask: True

[BrightContrastModule.getBrightnessByChannelinColorSpace:YUV]
limit_to_mask: True
to_color_space: YUV

[DeconvolutionModule.separateStains]
stain: hed_from_rgb
use_mask: True

[SaveModule.saveFinalMask]
overlay: True

[SaveModule.saveMacro]
dim: 500

[SaveModule.saveThumbnails]
image_work_size: 1.25x
small_dim: 500

[BasicModule.finalComputations]
mask_statistics = absolute
```

--------------------------------

### Install HistoQC via Pip

Source: https://context7.com/choosehappy/histoqc/llms.txt

Install HistoQC using pip after cloning the repository. It's recommended to use a virtual environment.

```bash
# Clone the repository
git clone https://github.com/choosehappy/HistoQC.git
cd HistoQC

# Create and activate virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install HistoQC
pip install .

# Verify installation
histoqc --help
```

--------------------------------

### Install HistoQC with Pip

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/installation.md

Install HistoQC using pip after cloning the repository and setting up a virtual environment. This command installs the package from the local source.

```bash
pip install .
```

--------------------------------

### Start HistoQC User Interface Server

Source: https://github.com/choosehappy/histoqc/wiki/Home

Run this command to start the HistoQC UI server for remotely viewing analysis results. Connect via a web browser to the specified IP address and port.

```bash
python -m histoqc.ui
```

--------------------------------

### Verify HistoQC Installation

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/installation.md

Run this command to confirm that HistoQC has been installed correctly. It should display the command-line interface usage instructions.

```bash
histoqc --help
```

--------------------------------

### Install HistoQC via Docker

Source: https://context7.com/choosehappy/histoqc/llms.txt

Use this command to pull and run the official HistoQC Docker image. Mount a local directory to persist data.

```bash
# Pull and run the official HistoQC Docker image
docker run -v /local/datadir:/data --name my_container -p 5000:5000 -it histotools/histoqc:master /bin/bash

# Inside the container, verify installation
histoqc --help
```

--------------------------------

### Specify Custom Configuration File

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/configuring_histoqc.md

Use the `-c` flag to specify a custom configuration file. The `--show` option can be used to generate example configuration files.

```bash
histoqc.config --show light > mylight.ini
histoqc -c ./mylight.ini -n 3 "*.svs"
```

--------------------------------

### Launch HistoQC Results Viewer

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/viewing_results.md

Run this command in your terminal to start the HistoQC results viewer. Specify the path to your results file. Access the viewer via http://<hostname>:5000 in your web browser.

```bash
histoqc.ui <results-file-path>
```

--------------------------------

### Subset Training Data for ClassificationModule.byExample

Source: https://github.com/choosehappy/histoqc/blob/master/CHANGELOG.md

Use `nsamples_per_example` to control the number of training data samples for a classifier. Setting it to -1 uses all examples, equivalent to the previous default behavior.

```python
nsamples_per_example = -1
```

--------------------------------

### BasicModule: Get Basic Statistics

Source: https://context7.com/choosehappy/histoqc/llms.txt

Extract essential slide metadata such as vendor, dimensions, and magnification. Ensure `image_work_size` is set appropriately.

```ini
[BasicModule.getBasicStats]
image_work_size = 1.25x
```

--------------------------------

### Detect Coverslip Edges with ClassificationModule

Source: https://context7.com/choosehappy/histoqc/llms.txt

Uses ClassificationModule.byExampleWithFeatures to detect coverslip edges based on provided examples and features. Requires feature extraction and area thresholds.

```ini
[ClassificationModule.byExampleWithFeatures:coverslip_edge]
name: coverslip_edge
threshold: .5
examples: ./models/coverslip_edge_he/coverslip_edge.png:./models/coverslip_edge_he/coverslip_edge_mask.png
nsamples_per_example: 10000
area_threshold: 15
features:  frangi
           laplace
           rgb
dilate_kernel_size: 5
```

--------------------------------

### ClassificationModule: Detect Pen Markings

Source: https://context7.com/choosehappy/histoqc/llms.txt

Use a Random Forest classifier to detect pen markings based on example images. Configure `threshold`, `nsamples_per_example`, and `area_threshold`.

```ini
# Detect pen markings using Random Forest classifier
[ClassificationModule.byExampleWithFeatures:pen_markings]
name: pen_markings
threshold: .5

# Training examples: image:mask pairs (supports multiple)
examples: ./pen/1k_version/pen_green.png:./pen/1k_version/pen_green_mask.png
          ./pen/1k_version/pen_red.png:./pen/1k_version/pen_red_mask.png
          ./pen/1k_version/pen_black.png:./pen/1k_version/pen_black_mask.png

# Subsampling for faster training
nsamples_per_example: 10000

# Minimum artifact size to detect
area_threshold: 100

# Feature extraction methods
features:  frangi
           laplace
           rgb
           #lbp
           #gabor
           #median

# Frangi filter parameters for vessel/line detection
frangi_scale_range: (1,10)
frangi_scale_step: 2
frangi_beta1: .5
frangi_beta2: 15
frangi_black_ridges: True

# Laplace edge detection kernel size
laplace_ksize: 3
```

--------------------------------

### List Available HistoQC Configuration Templates

Source: https://context7.com/choosehappy/histoqc/llms.txt

List all available configuration templates bundled with HistoQC.

```bash
# List all available configuration templates
histoqc.config --list
```

--------------------------------

### Set Up Python Virtual Environment

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/installation.md

It is recommended to use a virtual environment to manage Python dependencies for HistoQC. Activate the environment after creation.

```bash
python3 -m venv venv
source venv/bin/activate
```

--------------------------------

### Run HistoQC Pipeline - Basic Usage

Source: https://context7.com/choosehappy/histoqc/llms.txt

Basic command to process all SVS files with default configuration using 3 processes.

```bash
# Basic usage - process all SVS files with default config using 3 processes
histoqc -c v2.1 -n 3 "*.svs"
```

--------------------------------

### Run HistoQC Pipeline - Custom Configuration

Source: https://context7.com/choosehappy/histoqc/llms.txt

Process slides using a custom configuration file.

```bash
# Process with custom config file
histoqc -c ./my_custom_config.ini -n 2 "*.ndpi"
```

--------------------------------

### Launch HistoQC Results Viewer UI

Source: https://context7.com/choosehappy/histoqc/llms.txt

Launch the Flask web server for interactive visualization of quality control results. Access via a web browser.

```bash
# Launch UI server with default port (5000)
histoqc.ui /path/to/histoqc_output/results.tsv

# Launch UI on custom port
histoqc.ui --port 8080 /path/to/histoqc_output/results.tsv

# Access the web interface in browser
# Navigate to http://localhost:5000 (or custom port)
```

--------------------------------

### Show HistoQC Configuration Template Contents

Source: https://context7.com/choosehappy/histoqc/llms.txt

Display the contents of a specific configuration template. This can be redirected to a file for customization.

```bash
# Show contents of a specific configuration template
histoqc.config --show light

# Export configuration to file for customization
histoqc.config --show light > mylight.ini

# Use exported configuration
histoqc -c ./mylight.ini -n 3 "*.svs"
```

--------------------------------

### Run HistoQC Docker Image

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/installation.md

Use this command to run the official HistoQC Docker image. Mount a local directory to /data inside the container for persistent storage. Replace <local-path> with your directory and <container-name> with a desired name for the container. Map a local port to the container's port 5000.

```bash
docker run -v <local-path>:/data --name <container-name> -p <local-port>:5000 -it histotools/histoqc:master /bin/bash
```

```bash
# Example:
docker run -v /local/datadir:/data --name my_container -p 5000:5000 -it histotools/histoqc:master /bin/bash
```

--------------------------------

### View HistoQC Results in Web Interface

Source: https://context7.com/choosehappy/histoqc/llms.txt

Use this command to open the web interface for viewing HistoQC results. Ensure the path to the results file is correct.

```bash
histoqc.ui ./qc_output/results.tsv
```

--------------------------------

### HistoQC Command Line Interface Usage

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/running_histoqc.md

Displays the usage information for the HistoQC command-line tool, including available arguments.

```default
usage: histoqc [-h] [-o OUTDIR] [-p BASEPATH] [-c CONFIG] [-f] [-b BATCH]
               [-s SEED] [-n NPROCESSES] [--symlink TARGET_DIR] [--debug]
               input_pattern [input_pattern ...]
```

--------------------------------

### Run HistoQC Pipeline - Reproducibility and Symlink

Source: https://context7.com/choosehappy/histoqc/llms.txt

Set a random seed for reproducibility and create a symlink to the results directory.

```bash
# Set random seed for reproducibility and create symlink to results
histoqc -c v2.1 -n 4 -s 42 --symlink /results/symlinks "*.svs"
```

--------------------------------

### HistoQC UI Command Line Usage

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/viewing_results.md

This displays the command-line interface usage for the HistoQC UI server. It shows available arguments for launching the server and viewing results.

```default
usage: histoqc.ui [-h] [--port PORT] resultsfilepath
```

--------------------------------

### HistoQC Basic Usage

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/running_histoqc.md

Demonstrates a typical command-line execution of HistoQC for processing image files.

```APIDOC
## Running HistoQC

### Basic Usage

A typical command line for running HistoQC looks like:

```bash
histoqc -c v2.1 -n 3 "*.svs"
```
```

--------------------------------

### Configure Background Measurements in HistoQC

Source: https://github.com/choosehappy/histoqc/blob/master/CHANGELOG.md

Use `prefix`, `invert`, and `mask_name` parameters in `_getContrast`, `_getBrightnessGray`, and `_getBrightnessByChannelinColorSpace` functions to compute metrics on the background (inverted mask). This helps identify anomalies like dust or white-balance issues.

```python
prefix = "background"
invert = True
mask_name = "img_mask_use"
```

--------------------------------

### HistoQC Config Command Usage

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/configuring_histoqc.md

Displays the usage information for the `histoqc.config` command, including options for listing and showing configuration files.

```text
usage: histoqc.config [-h] [--list] [--show NAME]
```

--------------------------------

### Define HistoQC Pipeline Steps

Source: https://github.com/choosehappy/histoqc/wiki/Home

Specifies the sequence of modules and their configurations for image processing. Use module names followed by a colon and an instance name for repeated modules with different settings.

```ini
[pipeline]
steps= BasicModule.getBasicStats
    BasicModule.getMag
    ClassificationModule.byExampleWithFeatures:pen_markings
    #ClassificationModule.byExampleWithFeatures:pen_markings_red
    ClassificationModule.byExampleWithFeatures:coverslip_edge
    #LightDarkModule.getIntensityThresholdPercent:bubble
    LightDarkModule.getIntensityThresholdPercent:tissue
    #BubbleRegionByRegion.pixelWise
    LightDarkModule.getIntensityThresholdPercent:darktissue
    MorphologyModule.removeSmallObjects
    MorphologyModule.fillSmallHoles
    BlurDetectionModule.identifyBlurryRegions
    BasicModule.finalProcessingSpur
    BasicModule.finalProcessingArea
    HistogramModule.compareToTemplates
    HistogramModule.getHistogram
    BrightContrastModule.getContrast
    BrightContrastModule.getBrightness
    DeconvolutionModule.seperateStains
    SaveModule.saveFinalMask
    SaveModule.saveThumbnail
    BasicModule.finalComputations

```

--------------------------------

### HistoQC Pipeline Steps Configuration

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/wiki/pipeline_configuration.md

Defines the sequence of modules to be executed for image processing. Modules can be used multiple times with unique instance names specified after a double colon.

```ini
[pipeline]
steps= BasicModule.getBasicStats
    BasicModule.getMag
    ClassificationModule.byExampleWithFeatures:pen_markings
    #ClassificationModule.byExampleWithFeatures:pen_markings_red
    ClassificationModule.byExampleWithFeatures:coverslip_edge
    #LightDarkModule.getIntensityThresholdPercent:bubble
    LightDarkModule.getIntensityThresholdPercent:tissue
    #BubbleRegionByRegion.pixelWise
    LightDarkModule.getIntensityThresholdPercent:darktissue
    MorphologyModule.removeSmallObjects
    MorphologyModule.fillSmallHoles
    BlurDetectionModule.identifyBlurryRegions
    BasicModule.finalProcessingSpur
    BasicModule.finalProcessingArea
    HistogramModule.compareToTemplates
    HistogramModule.getHistogram
    BrightContrastModule.getContrast
    BrightContrastModule.getBrightness
    DeconvolutionModule.seperateStains
    SaveModule.saveFinalMask
    SaveModule.saveThumbnail
    BasicModule.finalComputations
```

--------------------------------

### Run HistoQC Unit Tests with Coverage

Source: https://github.com/choosehappy/histoqc/blob/master/histoqc/tests/readme.md

Execute unit tests for HistoQC and generate an XML coverage report. Ensure Python 3.7 or 3.8 is used.

```bash
python3 -m pytest --cov-report xml:./histoqc/tests/coverage.xml --cov=histoqc histoqc/tests/
```

--------------------------------

### Compute Background Contrast Metrics with BrightContrastModule

Source: https://context7.com/choosehappy/histoqc/llms.txt

Calculates contrast metrics for the background using BrightContrastModule.getContrast:background. Inverts the mask and allows specifying a prefix and mask name.

```ini
[BrightContrastModule.getContrast:background]
prefix: background
limit_to_mask: True
invert: True
mask_name: img_mask_use
```

--------------------------------

### Run HistoQC Pipeline - Custom Output and File Paths

Source: https://context7.com/choosehappy/histoqc/llms.txt

Process specific files with a custom output directory and number of processes.

```bash
# Process specific files with custom output directory
histoqc -c default -o ./qc_results -n 4 "/path/to/slides/*.svs"
```

--------------------------------

### BrightContrastModule

Source: https://context7.com/choosehappy/histoqc/llms.txt

Computes brightness and contrast metrics in various color spaces.

```APIDOC
## POST /api/brightContrast/getContrast

### Description
Computes RMS and Michelson contrast metrics.

### Method
POST

### Endpoint
/api/brightContrast/getContrast

### Parameters
#### Request Body
- **limit_to_mask** (boolean) - Optional - Whether to limit the computation to a mask.
- **prefix** (string) - Optional - Prefix for the output metric names (used for background contrast).
- **invert** (boolean) - Optional - Whether to invert the mask for computation (used for background contrast).
- **mask_name** (string) - Optional - The name of the mask to use.

### Request Example
```json
{
  "limit_to_mask": true,
  "prefix": "background",
  "invert": true,
  "mask_name": "img_mask_use"
}
```

### Response
#### Success Response (200)
- **contrast_result** (object) - The computed contrast metrics.

#### Response Example
```json
{
  "contrast_result": {}
}
```
```

```APIDOC
## POST /api/brightContrast/getBrightnessGray

### Description
Computes grayscale brightness metrics.

### Method
POST

### Endpoint
/api/brightContrast/getBrightnessGray

### Parameters
#### Request Body
- **limit_to_mask** (boolean) - Optional - Whether to limit the computation to a mask.

### Request Example
```json
{
  "limit_to_mask": true
}
```

### Response
#### Success Response (200)
- **brightness_result** (object) - The computed grayscale brightness metrics.

#### Response Example
```json
{
  "brightness_result": {}
}
```
```

```APIDOC
## POST /api/brightContrast/getBrightnessByChannelinColorSpace

### Description
Computes brightness metrics per RGB channel or in a specified color space.

### Method
POST

### Endpoint
/api/brightContrast/getBrightnessByChannelinColorSpace

### Parameters
#### Request Body
- **limit_to_mask** (boolean) - Optional - Whether to limit the computation to a mask.
- **to_color_space** (string) - Optional - The target color space (e.g., 'RGB', 'YUV').

### Request Example
```json
{
  "limit_to_mask": true,
  "to_color_space": "YUV"
}
```

### Response
#### Success Response (200)
- **brightness_result** (object) - The computed brightness metrics.

#### Response Example
```json
{
  "brightness_result": {}
}
```
```

--------------------------------

### Compute Contrast Metrics with BrightContrastModule

Source: https://context7.com/choosehappy/histoqc/llms.txt

Calculates RMS and Michelson contrast using BrightContrastModule.getContrast. Can be limited to a mask.

```ini
[BrightContrastModule.getContrast]
limit_to_mask: True
```

--------------------------------

### Clone HistoQC Repository

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/installation.md

Clone the HistoQC repository to your local machine using git and navigate into the directory.

```bash
git clone https://github.com/choosehappy/HistoQC.git
cd HistoQC
```

--------------------------------

### Basic HistoQC Command

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/running_histoqc.md

A typical command to run HistoQC with a specific configuration and number of processes.

```bash
histoqc -c v2.1 -n 3 "*.svs"
```

--------------------------------

### Run HistoQC Pipeline Command

Source: https://context7.com/choosehappy/histoqc/llms.txt

Command-line interface command to execute the HistoQC pipeline. Specifies configuration file, number of cores, output directory, and input image files.

```bash
# Run HistoQC pipeline
histoqc -c v2.1 -n 4 -o ./qc_output "*.svs"

# Output directory structure:
# ./qc_output/

```

--------------------------------

### Configure Exemplar Images for Classification

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/wiki/adding_classification_type_modules.md

Specify exemplar images and their corresponding binary masks for training classification models. Paths can be relative or absolute. Ensure exemplar images match the 'image_work_size' for better performance.

```default
examples: ./pen/1k_version/pen_green.png:./pen/1k_version/pen_green_mask.png
          #./pen/1k_version/pen_red.png:./pen/1k_version/pen_red_mask.png
```

--------------------------------

### Run HistoQC Pipeline - TSV File List

Source: https://context7.com/choosehappy/histoqc/llms.txt

Process slides listed in a TSV file, specifying a base path for the files.

```bash
# Process using a TSV file list
histoqc -c light -n 8 -p /base/path slides_list.tsv
```

--------------------------------

### Construct Output Image Filename

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/wiki/extending_histoqc.md

This code segment shows how to construct the base filename for output images by combining the output directory, system separator, and base filename. Avoid changing this structure unless necessary.

```python
s["outdir"] + os.sep + s["filename"]
```

--------------------------------

### LightDarkModule: Dynamic Otsu Thresholding

Source: https://context7.com/choosehappy/histoqc/llms.txt

Apply Otsu's method for thresholding, either locally or globally. Set `local` to `True` for local thresholding and adjust `radius` for local window size.

```ini
# Dynamic Otsu thresholding (local or global)
[LightDarkModule.getIntensityThresholdOtsu]
name: otsu_tissue
local: False
radius: 15
invert: False
```

--------------------------------

### HistoQC Command Line Interface

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/running_histoqc.md

Provides a detailed overview of the HistoQC command-line arguments, including positional and named options.

```APIDOC
## Command Line Interface

Run HistoQC main quality control pipeline for digital pathology images

```default
usage: histoqc [-h] [-o OUTDIR] [-p BASEPATH] [-c CONFIG] [-f] [-b BATCH]
               [-s SEED] [-n NPROCESSES] [--symlink TARGET_DIR] [--debug]
               input_pattern [input_pattern ...]
```

### Positional Arguments

*   **input_pattern** (string) - Path to input image files. Can be a glob pattern.

### Named Arguments

*   **-h, --help** - show this help message and exit
*   **-o OUTDIR, --outdir OUTDIR** - Directory to save QC results. Defaults to current directory.
*   **-p BASEPATH, --basepath BASEPATH** - Base path for output files. Defaults to current directory.
*   **-c CONFIG, --config CONFIG** - Configuration file to use. Defaults to `v2.1`.
*   **-f, --force** - Overwrite existing output files.
*   **-b BATCH, --batch BATCH** - Batch size for processing. Defaults to 100.
*   **-s SEED, --seed SEED** - Random seed for reproducibility. Defaults to None.
*   **-n NPROCESSES, --nprocesses NPROCESSES** - Number of parallel processes to use. Defaults to 1.
*   **--symlink TARGET_DIR** - Create symlinks to input files in the specified directory.
*   **--debug** - Enable debug logging.
```

--------------------------------

### Run HistoQC Pipeline - Batched Output

Source: https://context7.com/choosehappy/histoqc/llms.txt

Process slides with batched output, splitting results into subsets of a specified size.

```bash
# Process with batched output (split results into subsets)
histoqc -c default -n 8 -b 100 "*.svs"
```

--------------------------------

### Configure Parameters for a Custom Module

Source: https://github.com/choosehappy/histoqc/wiki/Home

Define parameters for a specific module and function by adding a section named after the module and function, e.g., [HistogramModule.compareTemplates], to the configuration file.

```ini
[HistogramModule.compareTemplates]
parameter_name: parameter_value
```

--------------------------------

### Export HistoQC Package Data

Source: https://context7.com/choosehappy/histoqc/llms.txt

Export bundled package data, including models, pen marking templates, and histogram templates, to a local directory.

```bash
# Export package data to a directory
mkdir -p ./histoqc_data
histoqc.data ./histoqc_data

# This exports:
# - models/: Classifier models for coverslip edge detection
# - pen/: Pen marking template images
# - templates/: Histogram comparison templates
```

--------------------------------

### Logging Data with addToPrintList

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/wiki/extending_histoqc.md

Dynamically add values to the output TSV file and the frontend by using the `addToPrintList` function. Ensure the value is provided in string format.

```python
addToPrintList(name, val)

```

--------------------------------

### SaveModule Configuration Options

Source: https://context7.com/choosehappy/histoqc/llms.txt

Configuration options for the SaveModule to control the saving of masks, thumbnails, and overlay visualizations. Customize output with suffixes and dimensions.

```ini
# Save final binary mask and overlay visualization
[SaveModule.saveFinalMask]
overlay: True
use_mask: True
```

```ini
# Save slide macro/label image
[SaveModule.saveMacro]
dim: 500
```

```ini
# Save thumbnail images for UI
[SaveModule.saveThumbnails]
image_work_size: 1.25x
small_dim: 500
```

```ini
# Save mask with custom suffix
[SaveModule.saveMask]
suffix: my_custom_mask
```

```ini
# Export mask as GeoJSON annotation
[SaveModule.saveMask2Geojson]
mask_name: img_mask_use
suffix: tissue_annotation
```

--------------------------------

### Define HistoQC Processing Pipeline

Source: https://context7.com/choosehappy/histoqc/llms.txt

Configure the sequence of modules to execute in the HistoQC processing pipeline. Each step specifies a module and optional parameters.

```ini
[pipeline]
steps= BasicModule.getBasicStats
    LightDarkModule.getIntensityThresholdPercent:tissue
    LightDarkModule.getIntensityThresholdPercent:darktissue
    MorphologyModule.fillSmallHoles
    MorphologyModule.removeSmallObjects
    BlurDetectionModule.identifyBlurryRegions
    BasicModule.finalProcessingSpur
    BasicModule.finalProcessingArea
    HistogramModule.compareToTemplates
    HistogramModule.getHistogram
    BrightContrastModule.getContrast
    BrightContrastModule.getBrightnessGray
    DeconvolutionModule.separateStains
    SaveModule.saveFinalMask
    SaveModule.saveMacro
    SaveModule.saveThumbnails
    BasicModule.finalComputations
```

--------------------------------

### BasicModule: Final Computations - Mask Statistics

Source: https://context7.com/choosehappy/histoqc/llms.txt

Compute final pixel count statistics for the mask. Choose between 'absolute' or 'relative2image' for `mask_statistics`.

```ini
# Compute final pixel count statistics
[BasicModule.finalComputations]
# Options: absolute, relative2image (relative2mask not available here)
mask_statistics = absolute
```

--------------------------------

### Run HistoQC Pipeline - Force Overwrite

Source: https://context7.com/choosehappy/histoqc/llms.txt

Force overwrite of existing results when processing slides.

```bash
# Force overwrite of existing results
histoqc -c v2.1 -n 4 -f "*.svs"
```

--------------------------------

### Compute RGB Channel Brightness with BrightContrastModule

Source: https://context7.com/choosehappy/histoqc/llms.txt

Calculates brightness for each RGB channel using BrightContrastModule.getBrightnessByChannelinColorSpace. Analysis can be limited to a mask.

```ini
[BrightContrastModule.getBrightnessByChannelinColorSpace:RGB]
limit_to_mask: True
```

--------------------------------

### Select Pixel-Features for Classifier Training

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/wiki/adding_classification_type_modules.md

Choose from a list of available pixel-features to augment the original RGB space, enhancing classifier robustness. Parameters for each feature can be set using the feature name as a prefix.

```default
features:  frangi
           laplace
           rgb
           #lbp
           #gabor
           #median
           #gaussian
```

--------------------------------

### Color Space and Contrast Metrics

Source: https://github.com/choosehappy/histoqc/wiki/Home

Functions for computing color space metrics and contrast measures.

```APIDOC
## GET /api/metrics/brightness

### Description
Computes a triplet (one per color channel) in the desired color space. Useful for detecting outliers.

### Method
GET

### Endpoint
/api/metrics/brightness

### Parameters
#### Query Parameters
- **color_space** (string) - Required - The desired color space for computation.

### Response
#### Success Response (200)
- **brightness_triplet** (array) - An array containing the brightness values for each color channel.

#### Response Example
```json
{
  "brightness_triplet": [0.8, 0.7, 0.9]
}
```

## GET /api/metrics/contrast

### Description
Computes both RMS and Michelson contrast metrics.

### Method
GET

### Endpoint
/api/metrics/contrast

### Response
#### Success Response (200)
- **rms_contrast** (float) - The Root Mean Square contrast value.
- **michelson_contrast** (float) - The Michelson contrast value.

#### Response Example
```json
{
  "rms_contrast": 0.25,
  "michelson_contrast": 0.5
}
```
```

--------------------------------

### Compare Histogram to Templates with HistogramModule

Source: https://context7.com/choosehappy/histoqc/llms.txt

Compares a computed histogram to reference templates using HistogramModule.compareToTemplates. Requires specifying template image paths and the number of bins.

```ini
[HistogramModule.compareToTemplates]
limit_to_mask: True
bins: 20
templates= ./templates/template1.png
           ./templates/template2.png
           ./templates/template3.png
           ./templates/template4.png
```

--------------------------------

### AnnotationModule

Source: https://context7.com/choosehappy/histoqc/llms.txt

Loads annotation files (XML, GeoJSON) to define regions of interest.

```APIDOC
## POST /api/annotation/saveAnnotationMask

### Description
Loads annotation files and saves them as a mask.

### Method
POST

### Endpoint
/api/annotation/saveAnnotationMask

### Parameters
#### Request Body
- **format** (string) - Required - The format of the annotation file (e.g., 'xml', 'geojson').
- **file_path** (string) - Required - The path to the annotation file(s).
- **suffix** (string) - Optional - A suffix to append to the generated mask file name.

### Request Example
```json
{
  "format": "xml",
  "file_path": "/path/to/annotations",
  "suffix": "_annot"
}
```

### Response
#### Success Response (200)
- **annotation_result** (object) - The result of loading and saving the annotation mask.

#### Response Example
```json
{
  "annotation_result": {}
}
```
```

--------------------------------

### Accessing Image Metadata with 's'

Source: https://github.com/choosehappy/histoqc/blob/master/docs/source/wiki/extending_histoqc.md

Use the 's' dictionary to access image metadata such as filename, warnings, and output directory. This is useful for tracking image-specific information throughout the pipeline.

```python
s["warnings"]

```

```python
s["filename"]

```

```python
s["seed"]

```

```python
s["outdir"]

```

```python
s["os_handle"]

```

```python
s["image_work_size"]

```

```python
s["img_mask_use"]

```

```python
s["comments"]

```

```python
s["completed"]

```

--------------------------------

### Add Custom Module to HistoQC Pipeline

Source: https://github.com/choosehappy/histoqc/wiki/Home

To integrate a new module, add a line in the [pipeline] section of the configuration file, formatted as _filename._function. HistoQC will dynamically load the function at runtime.

```ini
[pipeline]
steps:
    - HistogramModule.compareTemplates
```

--------------------------------

### Annotation Module

Source: https://github.com/choosehappy/histoqc/wiki/Home

Function to load an Aperio XML file for masking regions.

```APIDOC
## POST /api/annotation/xml_mask

### Description
Loads an Aperio XML file to mask out regions of the image, limiting artifact detection and metric computation to solely regions of interest.

### Method
POST

### Endpoint
/api/annotation/xml_mask

### Parameters
#### Request Body
- **xml_file** (file) - Required - The Aperio XML file containing region annotations.

### Response
#### Success Response (200)
- **masked_image_regions** (array) - Information about the masked regions.

#### Response Example
```json
{
  "masked_image_regions": [
    {"region_id": 1, "coordinates": "..."},
    {"region_id": 2, "coordinates": "..."}
  ]
}
```
```

--------------------------------

### Save Output Image

Source: https://github.com/choosehappy/histoqc/wiki/Home

Saves a binary mask as a PNG image to the output directory. The filename is constructed using the output directory, image filename, and a custom mask name. The mask is converted to uint8 with values 0 and 255.

```python
import io
import os

io.imsave(s["outdir"] + os.sep + s["filename"] + "_BubbleBounds.png", mask.astype(np.uint8) * 255)
```

--------------------------------

### Load Annotation Mask with AnnotationModule

Source: https://context7.com/choosehappy/histoqc/llms.txt

Loads annotation files (XML, GeoJSON) to create a region of interest mask using AnnotationModule.saveAnnotationMask. Requires specifying the format, file path, and suffix.

```ini
[AnnotationModule.saveAnnotationMask]
format: xml
file_path: /path/to/annotations
suffix: _annot
```

--------------------------------

### Identify Blurry Regions with BlurDetectionModule

Source: https://context7.com/choosehappy/histoqc/llms.txt

Applies BlurDetectionModule.identifyBlurryRegions to detect out-of-focus areas using Laplacian-based methods. Parameters control image magnification, smoothing radius, and blur threshold.

```ini
[BlurDetectionModule.identifyBlurryRegions]
# Work at higher magnification for blur detection
image_work_size = 2.5x
# Gaussian smoothing radius for blur map
blur_radius: 100
# Threshold for blur classification (lower = stricter)
blur_threshold: .15
```

--------------------------------

### Compute YUV Brightness with BrightContrastModule

Source: https://context7.com/choosehappy/histoqc/llms.txt

Computes brightness in the YUV color space using BrightContrastModule.getBrightnessByChannelinColorSpace. Allows specifying the target color space and limiting analysis to a mask.

```ini
[BrightContrastModule.getBrightnessByChannelinColorSpace:YUV]
limit_to_mask: True
# Options: RGB, HSV, RGB CIE, XYZ, YUV, YIQ, YPbPr, YCbCr
to_color_space: YUV
```

--------------------------------

### Enable In-Memory Compression for HistoQC

Source: https://github.com/choosehappy/histoqc/blob/master/CHANGELOG.md

Set `in_memory_compression = True` to compress masks in memory, significantly reducing memory footprint per image. This may slightly increase processing time but allows for better thread utilization and concurrency.

```python
"in_memory_compression = True"
```

--------------------------------

### Configure Image Work Size in HistoQC

Source: https://context7.com/choosehappy/histoqc/llms.txt

Set the resolution for image processing using the `image_work_size` parameter. Supports magnification, downscaling, pyramid levels, and exact dimensions.

```ini
[BaseImage.BaseImage]
# Method 1: Magnification level (recommended)
# Processes image at specified apparent magnification
image_work_size = 1.25x

# Method 2: Downscaling factor (0 < value < 1)
# new_dimensions = original_dimensions * factor
image_work_size = 0.1

# Method 3: OpenSlide pyramid level (1 < value < 100)
# Level 0 = base, Level 1 = 4:1, Level 2 = 16:1, etc.
image_work_size = 2

# Method 4: Exact longest dimension (value > 100)
# Resizes image so longest edge equals this value
image_work_size = 500

# Enable in-memory compression to reduce memory footprint
in_memory_compression = True
```

--------------------------------

### Estimate Texture Features on Background with LocalTextureEstimationModule

Source: https://context7.com/choosehappy/histoqc/llms.txt

Computes GLCM texture features on the background using LocalTextureEstimationModule.estimateGreyComatrixFeatures:background. Parameters include patch size, number of patches, levels, features, and inversion.

```ini
[LocalTextureEstimationModule.estimateGreyComatrixFeatures:background]
prefix: background
patch_size: 32
npatches: 1000
nlevels: 8
feats: contrast:dissimilarity:homogeneity:ASM:energy:correlation
invert: True
mask_name: img_mask_use
```

--------------------------------

### Saving Outputs

Source: https://github.com/choosehappy/histoqc/wiki/Home

Functions for saving the final mask and thumbnails.

```APIDOC
## POST /api/save/final_mask

### Description
Saves both the output mask from HistoQC but also the overlay on the original image.

### Method
POST

### Endpoint
/api/save/final_mask

### Parameters
#### Request Body
- **output_mask** (image) - Required - The final output mask.
- **overlay_image** (image) - Optional - The overlay image.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the mask and overlay were saved.

#### Response Example
```json
{
  "message": "Final mask and overlay saved successfully."
}
```

## POST /api/save/thumbnails

### Description
Saves thumbnails for easier viewing. This needs to be completed for the UI to work.

### Method
POST

### Endpoint
/api/save/thumbnails

### Parameters
#### Request Body
- **thumbnail_data** (array) - Required - Data for generating thumbnails.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that thumbnails were saved.

#### Response Example
```json
{
  "message": "Thumbnails saved successfully."
}
```
```

--------------------------------

### Generate RGB Color Histogram with HistogramModule

Source: https://context7.com/choosehappy/histoqc/llms.txt

Computes an RGB color histogram using HistogramModule.getHistogram. Options include limiting the histogram to a mask and specifying the number of bins.

```ini
[HistogramModule.getHistogram]
limit_to_mask: True
bins: 20
```

--------------------------------

### Basic Image Statistics and Magnification

Source: https://github.com/choosehappy/histoqc/wiki/Home

Functions to retrieve basic image metadata and magnification.

```APIDOC
## GET /api/image/basic_stats

### Description
Pulls out metadata from the image header.

### Method
GET

### Endpoint
/api/image/basic_stats

### Response
#### Success Response (200)
- **metadata** (object) - An object containing various metadata fields from the image header.

#### Response Example
```json
{
  "metadata": {
    "creation_date": "2023-10-27",
    "scanner": "ScannerModelX"
  }
}
```

## GET /api/image/magnification

### Description
Pulls out the base magnification. This is required by HistoQC. In the future, we'll add the ability to predict magnification.

### Method
GET

### Endpoint
/api/image/magnification

### Response
#### Success Response (200)
- **magnification** (float) - The base magnification of the image.

#### Response Example
```json
{
  "magnification": 20.0
}
```
```

--------------------------------

### Pixel-wise Classification with Custom Markers

Source: https://context7.com/choosehappy/histoqc/llms.txt

Performs pixel-wise classification based on TSV color values using ClassificationModule.pixelWise. Requires a TSV file defining custom marker colors.

```ini
[ClassificationModule.pixelWise:custom_marker]
name: custom_marker
threshold: .5
tsv_file: ./my_marker_colors.tsv
```

--------------------------------

### Remove Fat-like Tissue with MorphologyModule

Source: https://context7.com/choosehappy/histoqc/llms.txt

Uses MorphologyModule.removeFatlikeTissue to remove patterns resembling fat tissue. Parameters include kernel size, maximum keep size, and fat cell size.

```ini
[MorphologyModule.removeFatlikeTissue]
kernel_size: 10
max_keep_size: 1000
fat_cell_size: 64
```

--------------------------------

### LocalTextureEstimationModule

Source: https://context7.com/choosehappy/histoqc/llms.txt

Computes gray-level co-occurrence matrix (GLCM) texture features.

```APIDOC
## POST /api/localTextureEstimation/estimateGreyComatrixFeatures

### Description
Estimates GLCM texture features on specified regions (background or final tissue).

### Method
POST

### Endpoint
/api/localTextureEstimation/estimateGreyComatrixFeatures

### Parameters
#### Request Body
- **prefix** (string) - Required - Prefix for the output texture feature names.
- **patch_size** (integer) - Optional - The size of the patches for feature extraction.
- **npatches** (integer) - Optional - The number of patches to sample.
- **nlevels** (integer) - Optional - The number of gray levels for quantization.
- **feats** (string) - Required - Comma-separated list of texture features to compute (e.g., 'contrast:dissimilarity:homogeneity:ASM:energy:correlation').
- **invert** (boolean) - Optional - Whether to invert the mask for computation.
- **mask_name** (string) - Optional - The name of the mask to use.

### Request Example
```json
{
  "prefix": "final",
  "patch_size": 32,
  "npatches": 1000,
  "nlevels": 8,
  "feats": "contrast:dissimilarity:homogeneity:ASM:energy:correlation",
  "invert": false,
  "mask_name": "img_mask_use"
}
```

### Response
#### Success Response (200)
- **texture_features** (object) - The computed texture features.

#### Response Example
```json
{
  "texture_features": {}
}
```
```

--------------------------------

### BasicModule: Final Processing - Spur Removal

Source: https://context7.com/choosehappy/histoqc/llms.txt

Remove small, spurious tissue 'arms' or extensions using morphological opening. Adjust `disk_radius` to control the size of features to remove.

```ini
# Remove spurious tissue "arms" using morphological opening
[BasicModule.finalProcessingSpur]
disk_radius: 5
```

--------------------------------

### Detect Smooth Bubble Regions with BubbleRegionByRegion

Source: https://context7.com/choosehappy/histoqc/llms.txt

Detects smooth regions characteristic of air bubbles using BubbleRegionByRegion.detectSmoothness. Configurable by threshold, kernel size, and minimum object size.

```ini
[BubbleRegionByRegion.detectSmoothness]
threshold: .01
kernel_size: 10
min_object_size: 500
```