Coverage for src/bioimageio/core/cli.py: 76%
457 statements
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-20 09:46 +0000
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-20 09:46 +0000
1"""bioimageio CLI
3Note: Some docstrings use a hair space ' '
4 to place the added '(default: ...)' on a new line.
5"""
7from __future__ import annotations
9import json
10import shutil
11import subprocess
12import sys
13from abc import ABC
14from argparse import RawTextHelpFormatter
15from collections.abc import Iterable, Mapping, Sequence
16from difflib import SequenceMatcher
17from functools import cached_property, partial
18from io import StringIO
19from pathlib import Path
20from pprint import pformat, pprint
21from typing import (
22 Annotated,
23 Any,
24 Literal,
25)
27import numpy as np
28import rich.markdown
29from loguru import logger
30from pydantic import (
31 AliasChoices,
32 BaseModel,
33 Field,
34 PlainSerializer,
35 WithJsonSchema,
36 model_validator,
37)
38from pydantic_settings import (
39 BaseSettings,
40 CliApp,
41 CliPositionalArg,
42 CliSettingsSource,
43 CliSubCommand,
44 JsonConfigSettingsSource,
45 PydanticBaseSettingsSource,
46 SettingsConfigDict,
47 YamlConfigSettingsSource,
48)
49from tqdm import tqdm
50from typing_extensions import assert_never
52import bioimageio.spec
53from bioimageio.core import __version__
54from bioimageio.spec import (
55 AnyModelDescr,
56 InvalidDescr,
57 ResourceDescr,
58 load_description,
59 save_bioimageio_package,
60 save_bioimageio_package_as_folder,
61 save_bioimageio_yaml_only,
62 settings,
63 update_format,
64 update_hashes,
65)
66from bioimageio.spec._internal.io import is_yaml_value
67from bioimageio.spec._internal.io_utils import open_bioimageio_yaml
68from bioimageio.spec._internal.types import FormatVersionPlaceholder, NotEmpty
69from bioimageio.spec.common import PermissiveFileSource
70from bioimageio.spec.dataset import DatasetDescr
71from bioimageio.spec.model import ModelDescr, v0_4, v0_5
72from bioimageio.spec.notebook import NotebookDescr
73from bioimageio.spec.utils import (
74 empty_cache,
75 ensure_description_is_model,
76 get_reader,
77 write_yaml,
78)
80from ._prediction_pipeline import (
81 create_prediction_pipeline,
82 create_remote_prediction_pipeline,
83)
84from ._utils import compare
85from .commands import WeightFormatArgAll, WeightFormatArgAny, package, test
86from .common import MemberId, SampleId, SupportedWeightsFormat
87from .digest_spec import create_sample_for_model, get_member_ids
88from .io import load_stat, save_sample, save_stat
89from .proc_setup import get_required_dataset_measures
90from .remote_backends import create_remote_model_adapter
91from .sample import Sample
92from .stat_calculators import compute_dataset_measures
93from .stat_measures import Measure, MeasureValue, Stat
94from .weight_converters._add_weights import add_weights
96WEIGHT_FORMAT_ALIASES = AliasChoices(
97 "weight-format",
98 "weights-format",
99 "weight_format",
100 "weights_format",
101)
104class CmdBase(BaseModel, use_attribute_docstrings=True, cli_implicit_flags=True):
105 pass
108class ArgMixin(BaseModel, use_attribute_docstrings=True, cli_implicit_flags=True):
109 pass
112class WithSummaryLogging(ArgMixin):
113 summary: list[Literal["display"] | Path] = Field(
114 default_factory=lambda: ["display"],
115 examples=[
116 Path("summary.md"),
117 Path("bioimageio_summaries/"),
118 ["display", Path("summary.md")],
119 ],
120 )
121 """Display the validation summary or save it as JSON, Markdown or HTML.
122 The format is chosen based on the suffix: `.json`, `.md`, `.html`.
123 If a folder is given (path w/o suffix) the summary is saved in all formats.
124 Choose/add `"display"` to render the validation summary to the terminal.
125 """
127 def log(self, descr: ResourceDescr | InvalidDescr):
128 _ = descr.validation_summary.log(self.summary)
131class WithSource(ArgMixin):
132 source: CliPositionalArg[str]
133 """Url/path to a (folder with a) bioimageio.yaml/rdf.yaml file
134 or a bioimage.io resource identifier, e.g. 'affable-shark'"""
136 @cached_property
137 def descr(self):
138 return load_description(self.source)
140 @property
141 def descr_id(self) -> str:
142 """a more user-friendly description id
143 (replacing legacy ids with their nicknames)
144 """
145 if isinstance(self.descr, InvalidDescr): 145 ↛ 146line 145 didn't jump to line 146 because the condition on line 145 was never true
146 return str(
147 (self.descr.model_extra or {}).get("id")
148 or (self.descr.model_extra or {}).get("name", "unknown")
149 )
151 nickname = None
152 if ( 152 ↛ 159line 152 didn't jump to line 159 because the condition on line 152 was always true
153 isinstance(self.descr.config, v0_5.Config)
154 and (bio_config := self.descr.config.bioimageio)
155 and bio_config.model_extra is not None
156 ):
157 nickname = bio_config.model_extra.get("nickname")
159 return str(nickname or self.descr.id or self.descr.name)
162class ValidateFormatCmd(CmdBase, WithSource, WithSummaryLogging):
163 """Validate the meta data format of a bioimageio resource."""
165 perform_io_checks: bool = Field(
166 settings.perform_io_checks, alias="perform-io-checks"
167 )
168 """Wether or not to perform validations that requires downloading remote files.
169 Note: Default value is set by `BIOIMAGEIO_PERFORM_IO_CHECKS` environment variable.
170 """
172 @cached_property
173 def descr(self):
174 return load_description(self.source, perform_io_checks=self.perform_io_checks)
176 def cli_cmd(self):
177 self.log(self.descr)
178 sys.exit(
179 0
180 if self.descr.validation_summary.status in ("valid-format", "passed")
181 else 1
182 )
185class TestCmd(CmdBase, WithSource, WithSummaryLogging):
186 """Test a bioimageio resource (beyond meta data formatting)."""
188 weight_format: WeightFormatArgAll = Field(
189 "all",
190 alias="weight-format",
191 validation_alias=WEIGHT_FORMAT_ALIASES,
192 )
193 """The weight format to limit testing to.
195 (only relevant for model resources)"""
197 devices: list[str] | None = Field(
198 None, validation_alias=AliasChoices("devices", "device")
199 )
200 """Device(s) to use"""
202 runtime_env: Literal["currently-active", "as-described"] | Path = Field(
203 "currently-active", alias="runtime-env"
204 )
205 """The python environment to run the tests in
206 - `"currently-active"`: use active Python interpreter
207 - `"as-described"`: generate a conda environment YAML file based on the model
208 weights description.
209 - A path to a conda environment YAML.
210 Note: The `bioimageio.core` dependency will be added automatically if not present.
211 """
213 working_dir: Path | None = Field(None, alias="working-dir")
214 """(for debugging) Directory to save any temporary files."""
216 determinism: Literal["seed_only", "full"] = "seed_only"
217 """Modes to improve reproducibility of test outputs."""
219 stop_early: bool = Field(
220 False, alias="stop-early", validation_alias=AliasChoices("stop-early", "x")
221 )
222 """Do not run further subtests after a failed one."""
224 format_version: FormatVersionPlaceholder | str = Field(
225 "discover", alias="format-version"
226 )
227 """The format version to use for testing.
228 - 'latest': Use the latest implemented format version for the given resource type (may trigger auto updating)
229 - 'discover': Use the format version as described in the resource description
230 - '0.4', '0.5', ...: Use the specified format version (may trigger auto updating)
231 """
233 def cli_cmd(self):
234 sys.exit(
235 test(
236 self.descr,
237 weight_format=self.weight_format,
238 devices=self.devices,
239 summary=self.summary,
240 runtime_env=self.runtime_env,
241 determinism=self.determinism,
242 format_version=self.format_version,
243 working_dir=self.working_dir,
244 )
245 )
248class PackageCmd(CmdBase, WithSource, WithSummaryLogging):
249 """Save a resource's metadata with its associated files."""
251 path: CliPositionalArg[Path]
252 """The path to write the (zipped) package to.
253 If it does not have a `.zip` suffix
254 this command will save the package as an unzipped folder instead."""
256 weight_format: WeightFormatArgAll = Field(
257 "all",
258 alias="weight-format",
259 validation_alias=WEIGHT_FORMAT_ALIASES,
260 )
261 """The weight format to include in the package (for model descriptions only)."""
263 def cli_cmd(self):
264 if isinstance(self.descr, InvalidDescr): 264 ↛ 265line 264 didn't jump to line 265 because the condition on line 264 was never true
265 self.log(self.descr)
266 raise TypeError(f"Invalid {self.descr.type} description.")
268 sys.exit(
269 package(
270 self.descr,
271 self.path,
272 weight_format=self.weight_format,
273 )
274 )
277def _get_stat(
278 model_descr: AnyModelDescr,
279 dataset: Iterable[Sample],
280 dataset_length: int,
281 stats_path: Path,
282 dataset_fits_in_memory: bool,
283) -> Stat:
284 req_dataset_meas, _ = get_required_dataset_measures(model_descr)
285 if not req_dataset_meas:
286 return {}
288 req_dataset_meas, _ = get_required_dataset_measures(model_descr)
290 if stats_path.exists(): 290 ↛ 291line 290 didn't jump to line 291 because the condition on line 290 was never true
291 logger.info("loading precomputed dataset measures from {}", stats_path)
292 stat = load_stat(stats_path)
293 for m in req_dataset_meas:
294 if m not in stat:
295 raise ValueError(f"Missing {m} in {stats_path}")
297 return stat
299 values = compute_dataset_measures(
300 req_dataset_meas,
301 tqdm(
302 dataset,
303 total=dataset_length,
304 desc="precomputing dataset stats",
305 unit="sample",
306 ),
307 dataset_fits_in_memory=dataset_fits_in_memory,
308 )
309 stat: dict[Measure, MeasureValue] = {k: v for k, v in values.items()}
310 save_stat(stat, stats_path)
311 return stat
314class UpdateCmdBase(CmdBase, WithSource, ABC):
315 output: Literal["display", "stdout"] | Path = "display"
316 """Output updated bioimageio.yaml to the terminal or write to a file.
317 Notes:
318 - `"display"`: Render to the terminal with syntax highlighting.
319 - `"stdout"`: Write to sys.stdout without syntax highligthing.
320 (More convenient for copying the updated bioimageio.yaml from the terminal.)
321 """
323 diff: bool | Path = Field(True, alias="diff")
324 """Output a diff of original and updated bioimageio.yaml.
325 If a given path has an `.html` extension, a standalone HTML file is written,
326 otherwise the diff is saved in unified diff format (pure text).
327 """
329 exclude_unset: bool = Field(True, alias="exclude-unset")
330 """Exclude fields that have not explicitly be set."""
332 exclude_defaults: bool = Field(False, alias="exclude-defaults")
333 """Exclude fields that have the default value (even if set explicitly)."""
335 @cached_property
336 def updated(self) -> ResourceDescr | InvalidDescr:
337 raise NotImplementedError
339 def cli_cmd(self):
340 original_yaml = open_bioimageio_yaml(self.source).unparsed_content
341 assert isinstance(original_yaml, str)
342 stream = StringIO()
344 save_bioimageio_yaml_only(
345 self.updated,
346 stream,
347 exclude_unset=self.exclude_unset,
348 exclude_defaults=self.exclude_defaults,
349 )
350 updated_yaml = stream.getvalue()
352 diff = compare(
353 original_yaml.split("\n"),
354 updated_yaml.split("\n"),
355 diff_format=(
356 "html"
357 if isinstance(self.diff, Path) and self.diff.suffix == ".html"
358 else "unified"
359 ),
360 )
362 if isinstance(self.diff, Path): 362 ↛ 363line 362 didn't jump to line 363 because the condition on line 362 was never true
363 _ = self.diff.write_text(diff, encoding="utf-8")
364 elif self.diff: 364 ↛ 369line 364 didn't jump to line 369 because the condition on line 364 was always true
365 console = rich.console.Console()
366 diff_md = f"## Diff\n\n````````diff\n{diff}\n````````"
367 console.print(rich.markdown.Markdown(diff_md))
369 if isinstance(self.output, Path): 369 ↛ 370line 369 didn't jump to line 370 because the condition on line 369 was never true
370 if self.output.suffix in (".yaml", ".yml"):
371 _ = self.output.write_text(updated_yaml, encoding="utf-8")
372 logger.info(f"written updated description to {self.output}")
373 elif isinstance(self.updated, InvalidDescr):
374 raise ValueError(
375 f"Cannot save invalid description package to {self.output}."
376 + " To save the metadata only, choose an output with a '.yaml' extension."
377 )
379 elif not self.output.suffix:
380 _ = save_bioimageio_package_as_folder(
381 self.updated, output_path=self.output
382 )
383 else:
384 _ = save_bioimageio_package(self.updated, output_path=self.output)
386 elif self.output == "display":
387 updated_md = f"## Updated bioimageio.yaml\n\n```yaml\n{updated_yaml}\n```"
388 rich.console.Console().print(rich.markdown.Markdown(updated_md))
389 elif self.output == "stdout":
390 print(updated_yaml)
391 else:
392 assert_never(self.output)
394 if isinstance(self.updated, InvalidDescr): 394 ↛ exitline 394 didn't return from function 'cli_cmd' because the condition on line 394 was always true
395 logger.warning("Update resulted in invalid description")
396 _ = self.updated.validation_summary.display()
399class UpdateFormatCmd(UpdateCmdBase):
400 """Update the metadata format to the latest format version."""
402 exclude_defaults: bool = Field(True, alias="exclude-defaults")
403 """Exclude fields that have the default value (even if set explicitly).
405 Note:
406 The update process sets most unset fields explicitly with their default value.
407 """
409 perform_io_checks: bool = Field(
410 settings.perform_io_checks, alias="perform-io-checks"
411 )
412 """Wether or not to attempt validation that may require file download.
413 If `True` file hash values are added if not present."""
415 @cached_property
416 def updated(self):
417 return update_format(
418 self.source,
419 exclude_defaults=self.exclude_defaults,
420 perform_io_checks=self.perform_io_checks,
421 )
424class UpdateHashesCmd(UpdateCmdBase):
425 """Create a bioimageio.yaml description with updated file hashes."""
427 @cached_property
428 def updated(self):
429 return update_hashes(self.source)
432class PredictCmd(CmdBase, WithSource):
433 """Run inference on your data with a bioimage.io model."""
435 @cached_property
436 def descr(self):
437 return load_description(self.source, perform_io_checks=False)
439 inputs: NotEmpty[list[str | NotEmpty[list[str]]]] = Field(
440 default_factory=lambda: ["{input_id}/001.tif"],
441 validation_alias=AliasChoices("inputs", "input"),
442 )
443 """Model input sample paths (for each input tensor)
445 The input paths are expected to have shape...
446 - (n_samples,) or (n_samples,1) for models expecting a single input tensor
447 - (n_samples,) containing the substring '{input_id}', or
448 - (n_samples, n_model_inputs) to provide each input tensor path explicitly.
450 All substrings that are replaced by metadata from the model description:
451 - '{model_id}'
452 - '{input_id}'
454 Example inputs to process sample 'a' and 'b'
455 for a model expecting a 'raw' and a 'mask' input tensor:
456 --inputs="[[\\"a_raw.tif\\",\\"a_mask.tif\\"],[\\"b_raw.tif\\",\\"b_mask.tif\\"]]"
457 (Note that JSON double quotes need to be escaped.)
459 Alternatively a `bioimageio-cli.yaml` (or `bioimageio-cli.json`) file
460 may provide the arguments, e.g.:
461 ```yaml
462 inputs:
463 - [a_raw.tif, a_mask.tif]
464 - [b_raw.tif, b_mask.tif]
465 ```
467 `.npy` and any file extension supported by imageio are supported.
468 Aavailable formats are listed at
469 https://imageio.readthedocs.io/en/stable/formats/index.html#all-formats.
470 Some formats have additional dependencies.
473 """
475 outputs: str | NotEmpty[tuple[str, ...]] = Field(
476 "outputs_{model_id}/{output_id}/{sample_id}.tif",
477 validation_alias=AliasChoices("outputs", "output"),
478 )
479 """Model output path pattern (per output tensor)
481 All substrings that are replaced:
482 - '{model_id}' (from model description)
483 - '{output_id}' (from model description)
484 - '{sample_id}' (extracted from input paths)
486 """
488 overwrite: bool = False
489 """allow overwriting existing output files"""
491 blockwise: bool | int = False
492 """Process inputs blockwise
494 - If an integer is given, it is used as the blocksize parameter 'n' for blockwise processing.
495 The blockize parameter determines the block size along axes with parameterized input size
496 by adding n*step_size to the minimum valid input size.
497 - If `True`, the blocksize parameter is set to 10.
498 - If `False`, inputs are processed as a whole without blocking.
500 """
502 stats: Annotated[
503 Path,
504 WithJsonSchema({"type": "string"}),
505 PlainSerializer(lambda p: p.as_posix(), return_type=str),
506 ] = Path("precomputed_statistics.json")
507 """path to dataset statistics
508 (will be written if it does not exist
509 and the model requires statistical dataset measures)
510 """
512 preview: bool = False
513 """preview which files would be processed
514 and what outputs would be generated."""
516 weight_format: WeightFormatArgAny = Field(
517 "any",
518 alias="weight-format",
519 validation_alias=WEIGHT_FORMAT_ALIASES,
520 )
521 """The weight format to use."""
523 devices: list[str] | None = Field(
524 None, validation_alias=AliasChoices("devices", "device")
525 )
526 """Device(s) to use"""
528 server: str | None = None
529 """The URL or Hugging Face space name of a running bioimageio (gradio) server instance to use as a remote backend for prediction."""
531 pre_post_processing_location: Literal["local", "remote"] = Field(
532 "local", alias="pre-post-processing-location"
533 )
534 """Where to run preprocessing/postprocessing operations when using `--server`.
536 - `local`: Run preprocessing/postprocessing locally and only model inference on the server.
537 - `remote`: Run preprocessing/postprocessing on the server as well.
540 """
542 dataset_fits_in_memory: bool = False
543 """Allow dataset statistics to be computed in memory.
545 Note: Currently this only makes a difference for quantiles that are estimated from sample quantiles for OOM computation.
546 """
548 example: bool = False
549 """generate and run an example
551 1. downloads example model inputs
552 2. creates a `{model_id}_example` folder
553 3. writes input arguments to `{model_id}_example/bioimageio-cli.yaml`
554 4. executes a preview dry-run
555 5. executes prediction with example input
558 """
560 def _example(self):
561 model_descr = ensure_description_is_model(self.descr)
562 input_ids = get_member_ids(model_descr.inputs)
563 example_inputs = (
564 model_descr.sample_inputs
565 if isinstance(model_descr, v0_4.ModelDescr)
566 else [
567 t
568 for ipt in model_descr.inputs
569 if (t := ipt.sample_tensor or ipt.test_tensor)
570 ]
571 )
572 if not example_inputs: 572 ↛ 573line 572 didn't jump to line 573 because the condition on line 572 was never true
573 raise ValueError(f"{self.descr_id} does not specify any example inputs.")
575 inputs001: list[str] = []
576 example_path = Path(f"{self.descr_id}_example")
577 example_path.mkdir(exist_ok=True)
579 for t, src in zip(input_ids, example_inputs):
580 reader = get_reader(src)
581 dst = Path(f"{example_path}/{t}/001{reader.suffix}")
582 dst.parent.mkdir(parents=True, exist_ok=True)
583 inputs001.append(dst.as_posix())
584 with dst.open("wb") as f:
585 shutil.copyfileobj(reader, f)
587 inputs = [inputs001]
588 output_pattern = f"{example_path}/outputs/{{output_id}}/{{sample_id}}.tif"
590 bioimageio_cli_path = example_path / YAML_FILE
591 stats_file = "precomputed_statistics.json"
592 stats = (example_path / stats_file).as_posix()
593 cli_example_args = {
594 "inputs": inputs,
595 "outputs": output_pattern,
596 "stats": stats_file,
597 "blockwise": self.blockwise,
598 }
599 assert is_yaml_value(cli_example_args), cli_example_args
600 write_yaml(
601 cli_example_args,
602 bioimageio_cli_path,
603 )
605 yaml_file_content = None
607 # escaped double quotes
608 inputs_json = json.dumps(inputs)
609 inputs_escaped = inputs_json.replace('"', r"\"")
610 source_escaped = self.source.replace('"', r"\"")
612 def get_example_command(preview: bool, escape: bool = False):
613 q: str = '"' if escape else ""
615 return [
616 "bioimageio",
617 "predict",
618 # --no-preview not supported for py=3.8
619 *(["--preview"] if preview else []),
620 "--overwrite",
621 f"--blockwise={self.blockwise}",
622 f"--stats={q}{stats}{q}",
623 f"--inputs={q}{inputs_escaped if escape else inputs_json}{q}",
624 f"--outputs={q}{output_pattern}{q}",
625 f"{q}{source_escaped if escape else self.source}{q}",
626 ]
628 if Path(YAML_FILE).exists(): 628 ↛ 629line 628 didn't jump to line 629 because the condition on line 628 was never true
629 logger.info(
630 "temporarily removing '{}' to execute example prediction", YAML_FILE
631 )
632 yaml_file_content = Path(YAML_FILE).read_bytes()
633 Path(YAML_FILE).unlink()
635 try:
636 _ = subprocess.run(get_example_command(True), check=True)
637 _ = subprocess.run(get_example_command(False), check=True)
638 finally:
639 if yaml_file_content is not None: 639 ↛ 640line 639 didn't jump to line 640 because the condition on line 639 was never true
640 _ = Path(YAML_FILE).write_bytes(yaml_file_content)
641 logger.debug("restored '{}'", YAML_FILE)
643 print(
644 "🎉 Sucessfully ran example prediction!\n"
645 + "To predict the example input using the CLI example config file"
646 + f" {example_path / YAML_FILE}, execute `bioimageio predict` from {example_path}:\n"
647 + f"$ cd {example_path!s}\n"
648 + f'$ bioimageio predict "{source_escaped}"\n\n'
649 + "Alternatively run the following command"
650 + " in the current workind directory, not the example folder:\n$ "
651 + " ".join(get_example_command(False, escape=True))
652 + f"\n(note that a local '{JSON_FILE}' or '{YAML_FILE}' may interfere with this)"
653 )
655 def cli_cmd(self):
656 try:
657 for out_sample, out_path in self._yield_predictions(self.blockwise):
658 _ = save_sample(out_path, out_sample)
659 except Exception as e:
660 if not self.blockwise:
661 raise RuntimeError(
662 f"Prediction failed ({e}).\nConsider using blockwise processing, "
663 + "e.g. with `--blockwise=10` to process inputs in blocks."
664 ) from e
665 raise
667 def _yield_predictions(self, blockwise: bool | int):
668 if self.example:
669 return self._example()
671 model_descr = ensure_description_is_model(self.descr)
673 input_ids = get_member_ids(model_descr.inputs)
674 output_ids = get_member_ids(model_descr.outputs)
676 minimum_input_ids = tuple(
677 str(ipt.id) if isinstance(ipt, v0_5.InputTensorDescr) else str(ipt.name)
678 for ipt in model_descr.inputs
679 if not isinstance(ipt, v0_5.InputTensorDescr) or not ipt.optional
680 )
681 maximum_input_ids = tuple(
682 str(ipt.id) if isinstance(ipt, v0_5.InputTensorDescr) else str(ipt.name)
683 for ipt in model_descr.inputs
684 )
686 def expand_inputs(i: int, ipt: str | Sequence[str]) -> tuple[str, ...]:
687 if isinstance(ipt, str):
688 ipts = tuple(
689 ipt.format(model_id=self.descr_id, input_id=t) for t in input_ids
690 )
691 else:
692 ipts = tuple(
693 p.format(model_id=self.descr_id, input_id=t)
694 for t, p in zip(input_ids, ipt)
695 )
697 if len(set(ipts)) < len(ipts): 697 ↛ 698line 697 didn't jump to line 698 because the condition on line 697 was never true
698 if len(minimum_input_ids) == len(maximum_input_ids):
699 n = len(minimum_input_ids)
700 else:
701 n = f"{len(minimum_input_ids)}-{len(maximum_input_ids)}"
703 raise ValueError(
704 f"[input sample #{i}] Include '{{input_id}}' in path pattern or explicitly specify {n} distinct input paths (got {ipt})"
705 )
707 if len(ipts) < len(minimum_input_ids): 707 ↛ 708line 707 didn't jump to line 708 because the condition on line 707 was never true
708 raise ValueError(
709 f"[input sample #{i}] Expected at least {len(minimum_input_ids)} inputs {minimum_input_ids}, got {ipts}"
710 )
712 if len(ipts) > len(maximum_input_ids): 712 ↛ 713line 712 didn't jump to line 713 because the condition on line 712 was never true
713 raise ValueError(
714 f"Expected at most {len(maximum_input_ids)} inputs {maximum_input_ids}, got {ipts}"
715 )
717 return ipts
719 inputs = [expand_inputs(i, ipt) for i, ipt in enumerate(self.inputs, start=1)]
721 sample_paths_in = [
722 {
723 t: Path(p) if isinstance(p, str) and Path(p).exists() else p
724 for t, p in zip(input_ids, ipts)
725 }
726 for ipts in inputs
727 ]
729 sample_ids = _get_sample_ids(sample_paths_in)
731 def expand_outputs():
732 if isinstance(self.outputs, str):
733 try:
734 outputs = [
735 tuple(
736 Path(
737 self.outputs.format(
738 model_id=self.descr_id, output_id=t, sample_id=s
739 )
740 )
741 for t in output_ids
742 )
743 for s in sample_ids
744 ]
745 except Exception as e:
746 raise ValueError(
747 f"Failed to expand output path pattern '{self.outputs}' with model_id={self.descr_id}, output_id={output_ids}, sample_id={sample_ids}: {e}"
748 ) from e
749 else:
750 outputs = [
751 tuple(
752 Path(p.format(model_id=self.descr_id, output_id=t, sample_id=s))
753 for t, p in zip(output_ids, self.outputs)
754 )
755 for s in sample_ids
756 ]
757 # check for distinctness and correct number within each output sample
758 for i, out in enumerate(outputs, start=1):
759 if len(set(out)) < len(out): 759 ↛ 760line 759 didn't jump to line 760 because the condition on line 759 was never true
760 raise ValueError(
761 f"[output sample #{i}] Include '{{output_id}}' in path pattern or explicitly specify {len(output_ids)} distinct output paths (got {out})"
762 )
764 if len(out) != len(output_ids): 764 ↛ 765line 764 didn't jump to line 765 because the condition on line 764 was never true
765 raise ValueError(
766 f"[output sample #{i}] Expected {len(output_ids)} outputs {output_ids}, got {out}"
767 )
769 # check for distinctness across all output samples
770 all_output_paths = [p for out in outputs for p in out]
771 if len(set(all_output_paths)) < len(all_output_paths): 771 ↛ 772line 771 didn't jump to line 772 because the condition on line 771 was never true
772 raise ValueError(
773 "Output paths are not distinct across samples. "
774 + "Make sure to include '{{sample_id}}' in the output path pattern."
775 )
777 return outputs
779 outputs = expand_outputs()
781 sample_paths_out = [
782 {
783 MemberId(t): Path(p) if isinstance(p, str) and Path(p).exists() else p
784 for t, p in zip(output_ids, out)
785 }
786 for out in outputs
787 ]
789 if not self.overwrite:
790 for sample_paths in sample_paths_out:
791 for p in sample_paths.values():
792 if p.exists(): 792 ↛ 793line 792 didn't jump to line 793 because the condition on line 792 was never true
793 raise FileExistsError(
794 f"{p} already exists. use --overwrite to (re-)write outputs anyway."
795 )
796 if self.preview:
797 print("🛈 bioimageio prediction preview structure:")
798 pprint(
799 {
800 "{sample_id}": {
801 "inputs": {"{input_id}": "<input path>"},
802 "outputs": {"{output_id}": "<output path>"},
803 }
804 }
805 )
806 print("🔎 bioimageio prediction preview output:")
807 pprint(
808 {
809 s: {"inputs": sp_in, "outputs": sp_out}
810 for s, sp_in, sp_out in zip(
811 sample_ids, sample_paths_in, sample_paths_out
812 )
813 }
814 )
815 return
817 def input_dataset(stat: Stat):
818 for s, sp_in in zip(sample_ids, sample_paths_in):
819 yield create_sample_for_model(
820 model=model_descr,
821 inputs=sp_in,
822 stat=stat,
823 sample_id=s,
824 )
826 stat: dict[Measure, MeasureValue] = dict(
827 _get_stat(
828 model_descr,
829 input_dataset({}),
830 len(sample_ids),
831 self.stats,
832 dataset_fits_in_memory=self.dataset_fits_in_memory,
833 ).items()
834 )
836 if self.server is not None and self.pre_post_processing_location == "remote": 836 ↛ 837line 836 didn't jump to line 837 because the condition on line 836 was never true
837 pp = create_remote_prediction_pipeline(
838 model_descr, server=self.server, precomputed_statistics=stat
839 )
840 else:
841 if self.server is None: 841 ↛ 844line 841 didn't jump to line 844 because the condition on line 841 was always true
842 model_adapter = None
843 else:
844 assert self.pre_post_processing_location == "local"
845 model_adapter = create_remote_model_adapter(
846 model_descr, server=self.server
847 )
849 pp = create_prediction_pipeline(
850 model_descr,
851 weight_format=None
852 if self.weight_format == "any"
853 else self.weight_format,
854 devices=self.devices,
855 model_adapter=model_adapter,
856 fixed_dataset_statistics=stat,
857 )
859 if blockwise: 859 ↛ 860line 859 didn't jump to line 860 because the condition on line 859 was never true
860 predict_method = partial(
861 pp.predict_with_blocking,
862 ns=None if isinstance(blockwise, bool) else blockwise,
863 )
864 else:
865 predict_method = pp.predict_without_blocking
867 with pp:
868 for sample_in, sp_out in tqdm(
869 zip(input_dataset(dict(stat)), sample_paths_out),
870 total=len(inputs),
871 desc=f"predict with {self.descr_id}",
872 unit="sample",
873 ):
874 if self.blockwise is False and not isinstance( 874 ↛ 889line 874 didn't jump to line 889 because the condition on line 874 was always true
875 pp.model_description, v0_4.ModelDescr
876 ):
877 try:
878 _ = pp.model_description.validate_input_tensors(
879 {m: t.to_numpy() for m, t in sample_in.members.items()}
880 )
881 except Exception as e:
882 logger.warning(
883 "Input sample '{}' failed validation for whole-sample prediction: {}\n"
884 + "Consider using blockwise processing, e.g. with `--blockwise=10` to process inputs in blocks.",
885 sample_in.id,
886 e,
887 )
889 yield (predict_method(sample_in), sp_out)
892class PredictBlockArtifactsCmd(PredictCmd):
893 """Command to inspect block artifacts by subtracting the combined, blockwise predictions from a whole sample prediction.
895 Note:
896 - This command intentionally uses a small blocksize (default: 1) to create block artifacts for testing purposes.
897 - Typical sources of block artifacts include:
898 - Described halo is smaller than the model's receptive field
899 - Normalization layers inside the network cannot aggregate statistics over the whole sample.
900 """
902 blockwise: Literal[True] | int = 1
903 """Process inputs blockwise
905 - If an integer is given, it is used as the blocksize parameter 'n' for blockwise processing.
906 The blockize parameter determines the block size along axes with parameterized input size
907 by adding n*step_size to the minimum valid input size.
908 - If `True`, the blocksize parameter is set to 10.
910 Defaults to a small blocksize to intentionally create block artifacts for testing purposes.
911 """
913 def cli_cmd(self):
914 for (out_sample, out_path), (out_sample_blockwise, _) in zip(
915 self._yield_predictions(False), self._yield_predictions(self.blockwise)
916 ):
917 diff_sample = self._subtract_samples(out_sample, out_sample_blockwise)
918 for k, v_a in out_sample.stat.items():
919 v_b = out_sample_blockwise.stat.get(k)
920 if v_b is None:
921 logger.error(
922 "measure '{}' not found in blockwise prediction statistics", k
923 )
924 elif not np.not_equal(v_a, v_b):
925 logger.error(
926 "measure '{}' has different values (whole sample!=blockwise): {}!={}",
927 k,
928 v_a,
929 v_b,
930 )
932 _ = save_sample(out_path, diff_sample)
934 @staticmethod
935 def _subtract_samples(a: Sample, b: Sample) -> Sample:
936 return Sample(
937 members={t: a.members[t] - b.members[t] for t in a.members},
938 id=a.id,
939 stat=a.stat,
940 )
943class AddWeightsCmd(CmdBase, WithSource, WithSummaryLogging):
944 """Add additional weights to a model description by converting from available formats."""
946 output: CliPositionalArg[Path]
947 """The path to write the updated model package to."""
949 source_format: SupportedWeightsFormat | None = Field(None, alias="source-format")
950 """Exclusively use these weights to convert to other formats."""
952 target_format: SupportedWeightsFormat | None = Field(None, alias="target-format")
953 """Exclusively add this weight format."""
955 verbose: bool = False
956 """Log more (error) output."""
958 tracing: bool = True
959 """Allow tracing when converting pytorch_state_dict to torchscript
960 (still uses scripting if possible)."""
962 def cli_cmd(self):
963 model_descr = ensure_description_is_model(self.descr)
964 if isinstance(model_descr, v0_4.ModelDescr): 964 ↛ 965line 964 didn't jump to line 965 because the condition on line 964 was never true
965 raise TypeError(
966 f"model format {model_descr.format_version} not supported."
967 + " Please update the model first."
968 )
969 updated_model_descr = add_weights(
970 model_descr,
971 output_path=self.output,
972 source_format=self.source_format,
973 target_format=self.target_format,
974 verbose=self.verbose,
975 allow_tracing=self.tracing,
976 )
977 self.log(updated_model_descr)
980class EmptyCacheCmd(CmdBase):
981 """Empty the bioimageio cache directory."""
983 def cli_cmd(self):
984 empty_cache()
987class ServerCmd(CmdBase):
988 """Start a server to connect to with remote model adapters or remote prediction pipelines."""
990 backend: Literal["gradio"] = "gradio"
991 """The remote backend to use."""
993 port: int | None = None
994 """The port to start the server on. If not given, a free port will be used."""
996 devices: list[str] | None = Field(
997 None, validation_alias=AliasChoices("devices", "device")
998 )
999 """Devices to use for model inference. Defaults to automatic selection."""
1001 def cli_cmd(self) -> None:
1002 try:
1003 if self.backend == "gradio":
1004 from .remote_backends.gradio.server import main
1005 else:
1006 assert_never(self.backend)
1007 except ImportError as e:
1008 raise ImportError(
1009 f"{self.backend.capitalize()} is not installed. Please install the '{self.backend}-server' extra to use this command,"
1010 + f" e.g. with `pip install bioimageio.core[{self.backend}-server]`."
1011 ) from e
1013 local_server_url = main(port=self.port, devices=self.devices)
1014 logger.info(
1015 "{} server shutdown at {}", self.backend.capitalize(), local_server_url
1016 )
1019JSON_FILE = "bioimageio-cli.json"
1020YAML_FILE = "bioimageio-cli.yaml"
1023class Bioimageio(
1024 BaseSettings,
1025 cli_implicit_flags=True,
1026 cli_parse_args=True,
1027 cli_prog_name="bioimageio",
1028 cli_use_class_docs_for_groups=True,
1029 use_attribute_docstrings=True,
1030):
1031 """bioimageio - CLI for bioimage.io resources 🦒"""
1033 model_config = SettingsConfigDict(
1034 json_file=JSON_FILE,
1035 yaml_file=YAML_FILE,
1036 )
1038 validate_format: CliSubCommand[ValidateFormatCmd] = Field(alias="validate-format")
1039 """Check a resource's metadata format"""
1041 test: CliSubCommand[TestCmd]
1042 """Test a bioimageio resource (beyond meta data formatting)"""
1044 package: CliSubCommand[PackageCmd]
1045 """Package a resource"""
1047 predict: CliSubCommand[PredictCmd]
1048 """Predict with a model resource"""
1050 predict_block_artifacts: CliSubCommand[PredictBlockArtifactsCmd] = Field(
1051 alias="predict-block-artifacts"
1052 )
1053 """Save the difference between predicting blowise and whole sample to check for block artifacts."""
1055 update_format: CliSubCommand[UpdateFormatCmd] = Field(alias="update-format")
1056 """Update the metadata format"""
1058 update_hashes: CliSubCommand[UpdateHashesCmd] = Field(alias="update-hashes")
1059 """Create a bioimageio.yaml description with updated file hashes."""
1061 add_weights: CliSubCommand[AddWeightsCmd] = Field(alias="add-weights")
1062 """Add additional weights to a model description by converting from available formats."""
1064 empty_cache: CliSubCommand[EmptyCacheCmd] = Field(alias="empty-cache")
1065 """Empty the bioimageio cache directory."""
1067 server: CliSubCommand[ServerCmd]
1068 """Start a server to connect to with remote model adapters or remote prediction pipelines."""
1070 @classmethod
1071 def settings_customise_sources(
1072 cls,
1073 settings_cls: type[BaseSettings],
1074 init_settings: PydanticBaseSettingsSource,
1075 env_settings: PydanticBaseSettingsSource,
1076 dotenv_settings: PydanticBaseSettingsSource,
1077 file_secret_settings: PydanticBaseSettingsSource,
1078 ) -> tuple[PydanticBaseSettingsSource, ...]:
1079 cli: CliSettingsSource[BaseSettings] = CliSettingsSource(
1080 settings_cls,
1081 cli_parse_args=True,
1082 formatter_class=RawTextHelpFormatter,
1083 )
1084 sys_args = pformat(sys.argv)
1085 logger.info("starting CLI with arguments:\n{}", sys_args)
1086 return (
1087 cli,
1088 init_settings,
1089 YamlConfigSettingsSource(settings_cls),
1090 JsonConfigSettingsSource(settings_cls),
1091 )
1093 @model_validator(mode="before")
1094 @classmethod
1095 def _log(cls, data: Any):
1096 logger.info(
1097 "loaded CLI input:\n{}",
1098 pformat({k: v for k, v in data.items() if v is not None}),
1099 )
1100 return data
1102 def cli_cmd(self) -> None:
1103 logger.info(
1104 "executing CLI command:\n{}",
1105 pformat({k: v for k, v in self.model_dump().items() if v is not None}),
1106 )
1107 _ = CliApp.run_subcommand(self)
1110assert isinstance(Bioimageio.__doc__, str)
1111Bioimageio.__doc__ += f"""
1113library versions:
1114 bioimageio.core {__version__}
1115 bioimageio.spec {bioimageio.spec.__version__}
1117spec format versions:
1118 model RDF {ModelDescr.implemented_format_version}
1119 dataset RDF {DatasetDescr.implemented_format_version}
1120 notebook RDF {NotebookDescr.implemented_format_version}
1122"""
1125def _get_sample_ids(
1126 input_paths: Sequence[Mapping[MemberId, PermissiveFileSource]],
1127) -> Sequence[SampleId]:
1128 """Get sample ids for given input paths, based on the common path per sample.
1130 Falls back to sample01, samle02, etc..."""
1132 matcher = SequenceMatcher()
1134 def get_common_seq(seqs: Sequence[Sequence[str]]) -> Sequence[str]:
1135 """extract a common sequence from multiple sequences
1136 (order sensitive; strips whitespace and slashes)
1137 """
1138 common = seqs[0]
1140 for seq in seqs[1:]: 1140 ↛ 1141line 1140 didn't jump to line 1141 because the loop on line 1140 never started
1141 if not seq:
1142 continue
1143 matcher.set_seqs(common, seq)
1144 i, _, size = matcher.find_longest_match()
1145 common = common[i : i + size]
1147 if isinstance(common, str): 1147 ↛ 1150line 1147 didn't jump to line 1150 because the condition on line 1147 was always true
1148 common = common.strip().strip("/")
1149 else:
1150 common = [cs for c in common if (cs := c.strip().strip("/"))]
1152 if not common: 1152 ↛ 1153line 1152 didn't jump to line 1153 because the condition on line 1152 was never true
1153 raise ValueError(f"failed to find common sequence for {seqs}")
1155 return common
1157 def get_shorter_diff(seqs: Sequence[Sequence[str]]) -> list[Sequence[str]]:
1158 """get a shorter sequence whose entries are still unique
1159 (order sensitive, not minimal sequence)
1160 """
1161 min_seq_len = min(len(s) for s in seqs)
1162 # cut from the start
1163 for start in range(min_seq_len - 1, -1, -1): 1163 ↛ 1169line 1163 didn't jump to line 1169 because the loop on line 1163 didn't complete
1164 shortened = [s[start:] for s in seqs]
1165 if len(set(shortened)) == len(seqs): 1165 ↛ 1163line 1165 didn't jump to line 1163 because the condition on line 1165 was always true
1166 min_seq_len -= start
1167 break
1168 else:
1169 seen: set[Sequence[str]] = set()
1170 dupes = [s for s in seqs if s in seen or seen.add(s)]
1171 raise ValueError(f"Found duplicate entries {dupes}")
1173 # cut from the end
1174 for end in range(min_seq_len - 1, 1, -1): 1174 ↛ 1175line 1174 didn't jump to line 1175 because the loop on line 1174 never started
1175 shortened = [s[:end] for s in shortened]
1176 if len(set(shortened)) == len(seqs):
1177 break
1179 return shortened
1181 full_tensor_ids = [
1182 sorted(
1183 p.resolve().with_suffix("").as_posix() if isinstance(p, Path) else str(p)
1184 for p in input_sample_paths.values()
1185 )
1186 for input_sample_paths in input_paths
1187 ]
1188 try:
1189 long_sample_ids = [get_common_seq(t) for t in full_tensor_ids]
1190 sample_ids = get_shorter_diff(long_sample_ids)
1191 except ValueError as e:
1192 raise ValueError(f"failed to extract sample ids: {e}")
1194 return sample_ids