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

1"""bioimageio CLI 

2 

3Note: Some docstrings use a hair space ' ' 

4 to place the added '(default: ...)' on a new line. 

5""" 

6 

7from __future__ import annotations 

8 

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) 

26 

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 

51 

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) 

79 

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 

95 

96WEIGHT_FORMAT_ALIASES = AliasChoices( 

97 "weight-format", 

98 "weights-format", 

99 "weight_format", 

100 "weights_format", 

101) 

102 

103 

104class CmdBase(BaseModel, use_attribute_docstrings=True, cli_implicit_flags=True): 

105 pass 

106 

107 

108class ArgMixin(BaseModel, use_attribute_docstrings=True, cli_implicit_flags=True): 

109 pass 

110 

111 

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 """ 

126 

127 def log(self, descr: ResourceDescr | InvalidDescr): 

128 _ = descr.validation_summary.log(self.summary) 

129 

130 

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'""" 

135 

136 @cached_property 

137 def descr(self): 

138 return load_description(self.source) 

139 

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 ) 

150 

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") 

158 

159 return str(nickname or self.descr.id or self.descr.name) 

160 

161 

162class ValidateFormatCmd(CmdBase, WithSource, WithSummaryLogging): 

163 """Validate the meta data format of a bioimageio resource.""" 

164 

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 """ 

171 

172 @cached_property 

173 def descr(self): 

174 return load_description(self.source, perform_io_checks=self.perform_io_checks) 

175 

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 ) 

183 

184 

185class TestCmd(CmdBase, WithSource, WithSummaryLogging): 

186 """Test a bioimageio resource (beyond meta data formatting).""" 

187 

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. 

194 

195 (only relevant for model resources)""" 

196 

197 devices: list[str] | None = Field( 

198 None, validation_alias=AliasChoices("devices", "device") 

199 ) 

200 """Device(s) to use""" 

201 

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 """ 

212 

213 working_dir: Path | None = Field(None, alias="working-dir") 

214 """(for debugging) Directory to save any temporary files.""" 

215 

216 determinism: Literal["seed_only", "full"] = "seed_only" 

217 """Modes to improve reproducibility of test outputs.""" 

218 

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.""" 

223 

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 """ 

232 

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 ) 

246 

247 

248class PackageCmd(CmdBase, WithSource, WithSummaryLogging): 

249 """Save a resource's metadata with its associated files.""" 

250 

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.""" 

255 

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).""" 

262 

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.") 

267 

268 sys.exit( 

269 package( 

270 self.descr, 

271 self.path, 

272 weight_format=self.weight_format, 

273 ) 

274 ) 

275 

276 

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 {} 

287 

288 req_dataset_meas, _ = get_required_dataset_measures(model_descr) 

289 

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}") 

296 

297 return stat 

298 

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 

312 

313 

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 """ 

322 

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 """ 

328 

329 exclude_unset: bool = Field(True, alias="exclude-unset") 

330 """Exclude fields that have not explicitly be set.""" 

331 

332 exclude_defaults: bool = Field(False, alias="exclude-defaults") 

333 """Exclude fields that have the default value (even if set explicitly).""" 

334 

335 @cached_property 

336 def updated(self) -> ResourceDescr | InvalidDescr: 

337 raise NotImplementedError 

338 

339 def cli_cmd(self): 

340 original_yaml = open_bioimageio_yaml(self.source).unparsed_content 

341 assert isinstance(original_yaml, str) 

342 stream = StringIO() 

343 

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() 

351 

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 ) 

361 

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)) 

368 

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 ) 

378 

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) 

385 

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) 

393 

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() 

397 

398 

399class UpdateFormatCmd(UpdateCmdBase): 

400 """Update the metadata format to the latest format version.""" 

401 

402 exclude_defaults: bool = Field(True, alias="exclude-defaults") 

403 """Exclude fields that have the default value (even if set explicitly). 

404 

405 Note: 

406 The update process sets most unset fields explicitly with their default value. 

407 """ 

408 

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.""" 

414 

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 ) 

422 

423 

424class UpdateHashesCmd(UpdateCmdBase): 

425 """Create a bioimageio.yaml description with updated file hashes.""" 

426 

427 @cached_property 

428 def updated(self): 

429 return update_hashes(self.source) 

430 

431 

432class PredictCmd(CmdBase, WithSource): 

433 """Run inference on your data with a bioimage.io model.""" 

434 

435 @cached_property 

436 def descr(self): 

437 return load_description(self.source, perform_io_checks=False) 

438 

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) 

444 

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. 

449 

450 All substrings that are replaced by metadata from the model description: 

451 - '{model_id}' 

452 - '{input_id}' 

453 

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.) 

458 

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 ``` 

466 

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. 

471 

472   

473 """ 

474 

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) 

480 

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) 

485 

486  """ 

487 

488 overwrite: bool = False 

489 """allow overwriting existing output files""" 

490 

491 blockwise: bool | int = False 

492 """Process inputs blockwise 

493 

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. 

499 

500  """ 

501 

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  """ 

511 

512 preview: bool = False 

513 """preview which files would be processed 

514 and what outputs would be generated.""" 

515 

516 weight_format: WeightFormatArgAny = Field( 

517 "any", 

518 alias="weight-format", 

519 validation_alias=WEIGHT_FORMAT_ALIASES, 

520 ) 

521 """The weight format to use.""" 

522 

523 devices: list[str] | None = Field( 

524 None, validation_alias=AliasChoices("devices", "device") 

525 ) 

526 """Device(s) to use""" 

527 

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.""" 

530 

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`. 

535 

536 - `local`: Run preprocessing/postprocessing locally and only model inference on the server. 

537 - `remote`: Run preprocessing/postprocessing on the server as well. 

538 

539   

540 """ 

541 

542 dataset_fits_in_memory: bool = False 

543 """Allow dataset statistics to be computed in memory. 

544 

545 Note: Currently this only makes a difference for quantiles that are estimated from sample quantiles for OOM computation. 

546 """ 

547 

548 example: bool = False 

549 """generate and run an example 

550 

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 

556 

557   

558 """ 

559 

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.") 

574 

575 inputs001: list[str] = [] 

576 example_path = Path(f"{self.descr_id}_example") 

577 example_path.mkdir(exist_ok=True) 

578 

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) 

586 

587 inputs = [inputs001] 

588 output_pattern = f"{example_path}/outputs/{{output_id}}/{{sample_id}}.tif" 

589 

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 ) 

604 

605 yaml_file_content = None 

606 

607 # escaped double quotes 

608 inputs_json = json.dumps(inputs) 

609 inputs_escaped = inputs_json.replace('"', r"\"") 

610 source_escaped = self.source.replace('"', r"\"") 

611 

612 def get_example_command(preview: bool, escape: bool = False): 

613 q: str = '"' if escape else "" 

614 

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 ] 

627 

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() 

634 

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) 

642 

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 ) 

654 

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 

666 

667 def _yield_predictions(self, blockwise: bool | int): 

668 if self.example: 

669 return self._example() 

670 

671 model_descr = ensure_description_is_model(self.descr) 

672 

673 input_ids = get_member_ids(model_descr.inputs) 

674 output_ids = get_member_ids(model_descr.outputs) 

675 

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 ) 

685 

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 ) 

696 

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)}" 

702 

703 raise ValueError( 

704 f"[input sample #{i}] Include '{{input_id}}' in path pattern or explicitly specify {n} distinct input paths (got {ipt})" 

705 ) 

706 

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 ) 

711 

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 ) 

716 

717 return ipts 

718 

719 inputs = [expand_inputs(i, ipt) for i, ipt in enumerate(self.inputs, start=1)] 

720 

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 ] 

728 

729 sample_ids = _get_sample_ids(sample_paths_in) 

730 

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 ) 

763 

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 ) 

768 

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 ) 

776 

777 return outputs 

778 

779 outputs = expand_outputs() 

780 

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 ] 

788 

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 

816 

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 ) 

825 

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 ) 

835 

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 ) 

848 

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 ) 

858 

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 

866 

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 ) 

888 

889 yield (predict_method(sample_in), sp_out) 

890 

891 

892class PredictBlockArtifactsCmd(PredictCmd): 

893 """Command to inspect block artifacts by subtracting the combined, blockwise predictions from a whole sample prediction. 

894 

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 """ 

901 

902 blockwise: Literal[True] | int = 1 

903 """Process inputs blockwise 

904 

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. 

909 

910 Defaults to a small blocksize to intentionally create block artifacts for testing purposes. 

911  """ 

912 

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 ) 

931 

932 _ = save_sample(out_path, diff_sample) 

933 

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 ) 

941 

942 

943class AddWeightsCmd(CmdBase, WithSource, WithSummaryLogging): 

944 """Add additional weights to a model description by converting from available formats.""" 

945 

946 output: CliPositionalArg[Path] 

947 """The path to write the updated model package to.""" 

948 

949 source_format: SupportedWeightsFormat | None = Field(None, alias="source-format") 

950 """Exclusively use these weights to convert to other formats.""" 

951 

952 target_format: SupportedWeightsFormat | None = Field(None, alias="target-format") 

953 """Exclusively add this weight format.""" 

954 

955 verbose: bool = False 

956 """Log more (error) output.""" 

957 

958 tracing: bool = True 

959 """Allow tracing when converting pytorch_state_dict to torchscript 

960 (still uses scripting if possible).""" 

961 

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) 

978 

979 

980class EmptyCacheCmd(CmdBase): 

981 """Empty the bioimageio cache directory.""" 

982 

983 def cli_cmd(self): 

984 empty_cache() 

985 

986 

987class ServerCmd(CmdBase): 

988 """Start a server to connect to with remote model adapters or remote prediction pipelines.""" 

989 

990 backend: Literal["gradio"] = "gradio" 

991 """The remote backend to use.""" 

992 

993 port: int | None = None 

994 """The port to start the server on. If not given, a free port will be used.""" 

995 

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.""" 

1000 

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 

1012 

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 ) 

1017 

1018 

1019JSON_FILE = "bioimageio-cli.json" 

1020YAML_FILE = "bioimageio-cli.yaml" 

1021 

1022 

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 🦒""" 

1032 

1033 model_config = SettingsConfigDict( 

1034 json_file=JSON_FILE, 

1035 yaml_file=YAML_FILE, 

1036 ) 

1037 

1038 validate_format: CliSubCommand[ValidateFormatCmd] = Field(alias="validate-format") 

1039 """Check a resource's metadata format""" 

1040 

1041 test: CliSubCommand[TestCmd] 

1042 """Test a bioimageio resource (beyond meta data formatting)""" 

1043 

1044 package: CliSubCommand[PackageCmd] 

1045 """Package a resource""" 

1046 

1047 predict: CliSubCommand[PredictCmd] 

1048 """Predict with a model resource""" 

1049 

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.""" 

1054 

1055 update_format: CliSubCommand[UpdateFormatCmd] = Field(alias="update-format") 

1056 """Update the metadata format""" 

1057 

1058 update_hashes: CliSubCommand[UpdateHashesCmd] = Field(alias="update-hashes") 

1059 """Create a bioimageio.yaml description with updated file hashes.""" 

1060 

1061 add_weights: CliSubCommand[AddWeightsCmd] = Field(alias="add-weights") 

1062 """Add additional weights to a model description by converting from available formats.""" 

1063 

1064 empty_cache: CliSubCommand[EmptyCacheCmd] = Field(alias="empty-cache") 

1065 """Empty the bioimageio cache directory.""" 

1066 

1067 server: CliSubCommand[ServerCmd] 

1068 """Start a server to connect to with remote model adapters or remote prediction pipelines.""" 

1069 

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 ) 

1092 

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 

1101 

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) 

1108 

1109 

1110assert isinstance(Bioimageio.__doc__, str) 

1111Bioimageio.__doc__ += f""" 

1112 

1113library versions: 

1114 bioimageio.core {__version__} 

1115 bioimageio.spec {bioimageio.spec.__version__} 

1116 

1117spec format versions: 

1118 model RDF {ModelDescr.implemented_format_version} 

1119 dataset RDF {DatasetDescr.implemented_format_version} 

1120 notebook RDF {NotebookDescr.implemented_format_version} 

1121 

1122""" 

1123 

1124 

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. 

1129 

1130 Falls back to sample01, samle02, etc...""" 

1131 

1132 matcher = SequenceMatcher() 

1133 

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] 

1139 

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] 

1146 

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("/"))] 

1151 

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}") 

1154 

1155 return common 

1156 

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}") 

1172 

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 

1178 

1179 return shortened 

1180 

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}") 

1193 

1194 return sample_ids