TRIDENT: A Command-Line Pipeline for Whole-Slide Image Segmentation and Embedding

The gap TRIDENT fills between a slide directory and a feature matrix

A whole-slide image is a pyramid of tiles measured in gigapixels. Turning one into something a model can consume means deciding which regions contain tissue, cutting them into patches at a stated magnification, running each patch through an encoder, and then deciding whether to keep patch-level vectors or aggregate them into one vector per slide. Each of those steps has its own library, its own file formats and its own failure modes, and the encoders themselves come from different research groups with different preprocessing expectations. TRIDENT's stated purpose is to collapse that sequence into a single tool. The README describes an end-to-end pipeline covering tissue segmentation, patch coordinates and patch or slide embeddings, runnable in one command with --task all or stage by stage. The intended user is someone with a directory of slides and a downstream task, not someone building a new encoder. The 33 patch encoders and the slide encoder list (Titan, GigaPath, PRISM, CHIEF, Madeleine, Feather) are the substance of the offer: you get the wiring for models you would otherwise have to integrate yourself, at the cost of adopting TRIDENT's assumptions about resolution, patch size and output layout.

What actually happens between --wsi_dir and the output directory

The pipeline is a staged batch process. Stage one runs a segmenter over each slide to separate tissue from background; the README lists HEST, GrandQC and Otsu as the options, with Otsu described as a CPU-only fallback built on classical image processing. Optional flags --remove_artifacts and --remove_penmarks add a clean-up pass over the segmentation result. Stage two derives patch coordinates from the tissue mask. Stage three runs patches through the chosen patch encoder, and a separate path produces slide-level embeddings through one of the slide encoders. Reading the slides is itself pluggable: OpenSlide, CuCIM, plain images such as .png and .jpeg, SDPC, OME-Zarr and Zeiss CZI, with trident convert available to rewrite inputs as pyramidal TIFF. State is tracked per slide rather than per run. The README states that re-running on the same --job_dir skips already-completed work, that .lock files protect in-flight tasks, and that stale locks are cleared with --clear_dead_locks. Every run writes summary.md, a manifest at runs/<id>.json, and per-slide records under wsi_states/<slide>.json holding tasks, attempts, errors and resume information. That per-slide bookkeeping is the most consequential design decision in the project, because it determines what happens when a job dies eight hours into a hundred-slide batch.

Installation profiles and the flags that decide what runs

The README specifies Python 3.10 or 3.11, created with conda create -n "trident" python=3.10, followed by git clone of the repository and pip install -e . from inside it. The base install pulls the shared model stack, listed as timm>=0.9.16,<2, transformers>=4.51,<5 and safetensors. Everything beyond that is an optional extra: .[patch-encoders] for CONCH, MUSK and CTransPath or CHIEF, .[slide-encoders] for PRISM, GigaPath and Madeleine, .[omezarr] for OME-Zarr reading, .[czi] for Zeiss CZI through pylibCZIrw, .[convert] for slide conversion, and .[full] for all pip-installable optional dependencies. Before launching anything, the README recommends trident-doctor with a matching profile, and there is a --check-gated variant for the patch-encoder, slide-encoder and full profiles. That flag exists because some weights sit behind HuggingFace gated access, and the README notes that some models still need manual setup, giving the example of a local CHIEF repository path in trident/slide_encoder_models/local_ckpts.json. The single-slide entry point is python run_single_slide.py --slide_path ./wsis/xxxx.svs --job_dir ./trident_processed --patch_encoder uni_v1 --mag 20 --patch_size 256. The batch equivalent is python run_batch_of_slides.py --task all --wsi_dir ./wsis --job_dir ./trident_processed --patch_encoder uni_v1 --mag 20 --patch_size 256, or --task seg alone with --segmenter hest and --gpus 0. Passing -1 for --gpus forces CPU; passing several indices shards pending slides across them. The conversion path is separate: trident convert --input_dir ./wsis --mpp_csv ./wsis/to_process.csv --job_dir ./pyramidal_tiff --downscale_by 1 --num_workers 1, where the CSV is required, must carry wsi and mpp columns, and acts as an allowlist. The README states that when embedded MPP metadata is found, TRIDENT compares it against the CSV value and logs mismatches.

Where the pipeline is likely to bite you

The encoder and resolution pairing is not enforced by the flags. You pass --mag 20 --patch_size 256 and a patch encoder name, and the command runs; nothing in the documented interface stops you from combining an encoder with a magnification it was not trained for. The README's own note about the bundled Agent Skill at .claude/skills/trident/ is telling: it advertises that the skill carries the correct encoder-to-resolution pairings and output layout, which implies that getting those right is a known source of mistakes for people driving the CLI directly. Second, gated access is a hard external dependency. If an approval does not come through, trident-doctor --check-gated is where you find out, and the fallback is a different encoder, which changes your feature space and invalidates anything you already computed. Third, the resume mechanism is keyed to the job directory. Point two runs at the same --job_dir with different flags and the state files will not know your intent changed; the per-slide records track tasks and attempts, not the parameter set that produced them, at least as far as the README describes. Fourth, the segmentation stage is not neutral. HEST, GrandQC and Otsu produce different tissue masks, and the README attaches a non-commercial licence note to GrandQC specifically. TRIDENT is the wrong tool if you want a library to import into a custom training loop, or if you need to process slides in a streaming fashion rather than as a directory of files with a job directory on disk.

The cache pipeline, and why it is separate from resume

Slow or network-attached storage is treated as a distinct problem from interrupted jobs. The README documents --wsi_cache /local/ssd --cache_batch_size 32 as a way to stage slides locally through a producer and consumer pipeline. The distinction matters: resume protects you from losing completed work, while the cache protects you from re-reading the same slide from a slow mount across multiple stages. A run that segments, patches and embeds each slide reads the source file repeatedly, so on network storage the read cost is paid more than once per slide. Staging to local SSD with a bounded batch size changes that arithmetic. The README does not state a required size for the cache relative to the slide set, so the batch size is the knob you tune against available local disk. If your slides already sit on fast local storage, this flag is dead weight and adds a copy step.

How TRIDENT differs from assembling OpenSlide, timm and a feature extractor yourself

The obvious alternative is to write the loop yourself: OpenSlide or CuCIM to read the pyramid, a threshold or a small segmentation model for tissue, a tiling routine, and timm or transformers to run the encoder. That approach gives you control over the tiling grid, the batching strategy and the output format, and it does not require you to accept anyone else's directory layout. The cost is that you own every integration: the encoder preprocessing, the magnification convention, the multi-GPU sharding, the resume logic and the per-slide error records. TRIDENT's value is that all of those are already written and, per the README, are exercised by the same CLI across 33 patch encoders. The trade is that you inherit its conventions rather than choosing your own, and you cannot easily call one stage in isolation from your own code. CLAM is the other comparison point that will occur to anyone in computational pathology, since it also covers patching and slide-level modelling, but the README does not describe CLAM or position TRIDENT against it, so the honest statement is that TRIDENT's documented scope stops at producing patch and slide embeddings plus a conversion utility; what you train on those embeddings is outside what the material describes.

Maintenance, upgrade cost and the licence question

The release cadence is visible: v0.3.0 in May 2026, v0.3.1 in June, v0.3.2 in August, with the last push to main in the same month. Three minor releases in roughly four months means the interface is still moving, and the README's flag surface is broad enough that a minor bump can change a default. The stage-by-stage commands are the cheaper thing to depend on than the bundled --task all path, because a failure in one stage is diagnosable without unwinding the others. Upgrading also means re-checking the model stack, since the base install pins timm below 2 and transformers below 5; those bounds will eventually force a decision. On licensing, the repository metadata reports NOASSERTION, which means no licence was detected or declared in a form the tooling recognised, and the README links to a License section without stating terms in the text provided. That is not a detail to resolve after you have built a pipeline on top of it. Separately, the models TRIDENT orchestrates carry their own terms, and the README flags GrandQC as non-commercial use under CC BY-NC-SA 4.0, so a permissively licensed wrapper would not make the weights permissive. Check the repository's licence file and each encoder's terms before you depend on any of this in a product.

Editorial conclusion

Adopt TRIDENT if you already have a directory of WSIs and want segmentation, patching and embedding handled by one command with per-slide resume, and if you are willing to accept the HuggingFace gated-access approvals and the manual local checkpoint setup that some encoders still require. Do not adopt it if you need a clearly declared open source licence, if you cannot get access to the gated weights, or if you want a library to call from your own training loop rather than a batch runner driven by flags. Before committing, run trident-doctor with the profile that matches your intended encoders, including --check-gated, and read the repository's licence file directly, because the metadata carries NOASSERTION and that is the single hardest blocker to resolve after the fact.

Official sources

1. Issues
2. mahmoodlab/TRIDENT on GitHub
3. Project website
4. README
5. Releases