fujicv 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. fujicv-1.0.0/LICENSE +173 -0
  2. fujicv-1.0.0/PKG-INFO +254 -0
  3. fujicv-1.0.0/README.md +200 -0
  4. fujicv-1.0.0/fujicv/__init__.py +10 -0
  5. fujicv-1.0.0/fujicv/data/__init__.py +13 -0
  6. fujicv-1.0.0/fujicv/data/dataloader.py +102 -0
  7. fujicv-1.0.0/fujicv/data/datasets.py +332 -0
  8. fujicv-1.0.0/fujicv/data/transforms.py +93 -0
  9. fujicv-1.0.0/fujicv/engine/__init__.py +14 -0
  10. fujicv-1.0.0/fujicv/engine/callbacks.py +184 -0
  11. fujicv-1.0.0/fujicv/engine/logger.py +127 -0
  12. fujicv-1.0.0/fujicv/engine/trainer.py +290 -0
  13. fujicv-1.0.0/fujicv/eval/__init__.py +18 -0
  14. fujicv-1.0.0/fujicv/eval/attention_map.py +300 -0
  15. fujicv-1.0.0/fujicv/eval/curves.py +119 -0
  16. fujicv-1.0.0/fujicv/eval/plots.py +74 -0
  17. fujicv-1.0.0/fujicv/eval/report.py +57 -0
  18. fujicv-1.0.0/fujicv/eval/tsne.py +129 -0
  19. fujicv-1.0.0/fujicv/export/__init__.py +5 -0
  20. fujicv-1.0.0/fujicv/export/onnx.py +118 -0
  21. fujicv-1.0.0/fujicv/inference/__init__.py +5 -0
  22. fujicv-1.0.0/fujicv/inference/predictor.py +187 -0
  23. fujicv-1.0.0/fujicv/losses/__init__.py +13 -0
  24. fujicv-1.0.0/fujicv/losses/classification.py +165 -0
  25. fujicv-1.0.0/fujicv/losses/multilabel.py +152 -0
  26. fujicv-1.0.0/fujicv/losses/registry.py +25 -0
  27. fujicv-1.0.0/fujicv/losses/regression.py +97 -0
  28. fujicv-1.0.0/fujicv/metrics/__init__.py +12 -0
  29. fujicv-1.0.0/fujicv/metrics/classification.py +165 -0
  30. fujicv-1.0.0/fujicv/metrics/multilabel.py +75 -0
  31. fujicv-1.0.0/fujicv/metrics/registry.py +25 -0
  32. fujicv-1.0.0/fujicv/metrics/regression.py +83 -0
  33. fujicv-1.0.0/fujicv/models/__init__.py +19 -0
  34. fujicv-1.0.0/fujicv/models/backbone.py +195 -0
  35. fujicv-1.0.0/fujicv/models/builder.py +154 -0
  36. fujicv-1.0.0/fujicv/models/custom_layers.py +125 -0
  37. fujicv-1.0.0/fujicv/models/head.py +96 -0
  38. fujicv-1.0.0/fujicv/utils/__init__.py +13 -0
  39. fujicv-1.0.0/fujicv/utils/config.py +138 -0
  40. fujicv-1.0.0/fujicv/utils/registry.py +71 -0
  41. fujicv-1.0.0/fujicv/utils/seed.py +73 -0
  42. fujicv-1.0.0/fujicv.egg-info/PKG-INFO +254 -0
  43. fujicv-1.0.0/fujicv.egg-info/SOURCES.txt +50 -0
  44. fujicv-1.0.0/fujicv.egg-info/dependency_links.txt +1 -0
  45. fujicv-1.0.0/fujicv.egg-info/requires.txt +36 -0
  46. fujicv-1.0.0/fujicv.egg-info/top_level.txt +1 -0
  47. fujicv-1.0.0/pyproject.toml +85 -0
  48. fujicv-1.0.0/setup.cfg +4 -0
  49. fujicv-1.0.0/tests/test_data.py +152 -0
  50. fujicv-1.0.0/tests/test_losses.py +167 -0
  51. fujicv-1.0.0/tests/test_metrics.py +172 -0
  52. fujicv-1.0.0/tests/test_models.py +161 -0
fujicv-1.0.0/LICENSE ADDED
@@ -0,0 +1,173 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship made available under
36
+ the License, as indicated by a copyright notice that is included in
37
+ or attached to the work (an example is provided in the Appendix below).
38
+
39
+ "Derivative Works" shall mean any work, whether in Source or Object
40
+ form, that is based on (or derived from) the Work and for which the
41
+ editorial revisions, annotations, elaborations, or other modifications
42
+ represent, as a whole, an original work of authorship. For the purposes
43
+ of this License, Derivative Works shall not include works that remain
44
+ separable from, or merely link (or bind by name) to the interfaces of,
45
+ the Work and Derivative Works thereof.
46
+
47
+ "Contribution" shall mean, as submitted to the Licensor for inclusion
48
+ in the Work by the copyright owner or by an individual or Legal Entity
49
+ authorized to submit on behalf of the copyright owner. For the purposes
50
+ of this definition, "submitted" means any form of electronic, verbal,
51
+ or written communication sent to the Licensor or its representatives,
52
+ including but not limited to communication on electronic mailing lists,
53
+ source code control systems, and issue tracking systems that are managed
54
+ by, or on behalf of, the Licensor for the purpose of discussing and
55
+ improving the Work, but excluding communication that is conspicuously
56
+ marked or designated in writing by the copyright owner as "Not a
57
+ Contribution."
58
+
59
+ "Contributor" shall mean Licensor and any Legal Entity on behalf of
60
+ whom a Contribution has been received by the Licensor and included
61
+ within the Work.
62
+
63
+ 2. Grant of Copyright License. Subject to the terms and conditions of
64
+ this License, each Contributor hereby grants to You a perpetual,
65
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
66
+ copyright license to reproduce, prepare Derivative Works of,
67
+ publicly display, publicly perform, sublicense, and distribute the
68
+ Work and such Derivative Works in Source or Object form.
69
+
70
+ 3. Grant of Patent License. Subject to the terms and conditions of
71
+ this License, each Contributor hereby grants to You a perpetual,
72
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
73
+ (except as stated in this section) patent license to make, have made,
74
+ use, offer to sell, sell, import, and otherwise transfer the Work,
75
+ where such license applies only to those patent claims licensable
76
+ by such Contributor that are necessarily infringed by their
77
+ Contribution(s) alone or by the combination of their Contribution(s)
78
+ with the Work to which such Contribution(s) was submitted. If You
79
+ institute patent litigation against any entity (including a cross-claim
80
+ or counterclaim in a lawsuit) alleging that the Work or any Work
81
+ incorporated within the Work constitutes direct or contributory patent
82
+ infringement, then any patent licenses granted to You under this
83
+ License for that Work shall terminate as of the date such litigation
84
+ is filed.
85
+
86
+ 4. Redistribution. You may reproduce and distribute copies of the Work
87
+ or Derivative Works thereof in any medium, with or without
88
+ modifications, and in Source or Object form, provided that You meet
89
+ the following conditions:
90
+
91
+ (a) You must give any other recipients of the Work or Derivative Works
92
+ a copy of this License; and
93
+
94
+ (b) You must cause any modified files to carry prominent notices
95
+ stating that You changed the files; and
96
+
97
+ (c) You must retain, in the Source form of any Derivative Works that
98
+ You distribute, all copyright, patent, trademark, and attribution
99
+ notices from the Source form of the Work, excluding those notices
100
+ that do not pertain to any part of the Derivative Works; and
101
+
102
+ (d) If the Work includes a "NOTICE" text file as part of its
103
+ distribution, You must include a readable copy of the attribution
104
+ notices contained within such NOTICE file, in at least one of the
105
+ following places: within a NOTICE text file distributed as part of
106
+ the Derivative Works; within the Source form or documentation, if
107
+ provided along with the Derivative Works; or, within a display
108
+ generated by the Derivative Works, if and wherever such third-party
109
+ notices normally appear. The contents of the NOTICE file are for
110
+ informational purposes only and do not modify the License. You may
111
+ add Your own attribution notices within Derivative Works that You
112
+ distribute, alongside or in addition to the NOTICE text from the
113
+ Work, provided that such additional attribution notices cannot be
114
+ construed as modifying the License.
115
+
116
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
117
+ any Contribution intentionally submitted for inclusion in the Work by
118
+ You to the Licensor shall be under the terms and conditions of this
119
+ License, without any additional terms or conditions.
120
+
121
+ 6. Trademarks. This License does not grant permission to use the trade
122
+ names, trademarks, service marks, or product names of the Licensor,
123
+ except as required for reasonable and customary use in describing the
124
+ origin of the Work and reproducing the content of the NOTICE file.
125
+
126
+ 7. Disclaimer of Warranty. Unless required by applicable law or agreed
127
+ to in writing, Licensor provides the Work (and each Contributor
128
+ provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES
129
+ OR CONDITIONS OF ANY KIND, either express or implied, including,
130
+ without limitation, any warranties or conditions of TITLE,
131
+ NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE.
132
+ You are solely responsible for determining the appropriateness of using
133
+ or reproducing the Work and assume any risks associated with Your
134
+ exercise of permissions under this License.
135
+
136
+ 8. Limitation of Liability. In no event and under no legal theory,
137
+ whether in tort (including negligence), contract, or otherwise, unless
138
+ required by applicable law (such as deliberate and grossly negligent
139
+ acts) or agreed to in writing, shall any Contributor be liable to You
140
+ for damages, including any direct, indirect, special, incidental, or
141
+ exemplary damages of any character arising as a result of this License
142
+ or out of the use or inability to use the Work (including but not
143
+ limited to damages for loss of goodwill, work stoppage, computer
144
+ failure or malfunction, or all other commercial damages or losses),
145
+ even if such Contributor has been advised of the possibility of such
146
+ damages.
147
+
148
+ 9. Accepting Warranty or Liability. While redistributing the Work or
149
+ Derivative Works thereof, You may choose to offer, and charge a fee
150
+ for, acceptance of support, warranty, indemnity, or other liability
151
+ obligations and/or rights consistent with this License. However, in
152
+ accepting such obligations, You may offer such obligations only on
153
+ Your own behalf and on Your sole responsibility, not on behalf of any
154
+ other Contributor, and only if You agree to indemnify, defend, and hold
155
+ each Contributor harmless for any liability incurred by, or claims
156
+ asserted against, such Contributor by reason of your accepting any such
157
+ warranty or additional liability.
158
+
159
+ END OF TERMS AND CONDITIONS
160
+
161
+ Copyright 2025 FujiCV Contributors
162
+
163
+ Licensed under the Apache License, Version 2.0 (the "License");
164
+ you may not use this file except in compliance with the License.
165
+ You may obtain a copy of the License at
166
+
167
+ http://www.apache.org/licenses/LICENSE-2.0
168
+
169
+ Unless required by applicable law or agreed to in writing, software
170
+ distributed under the License is distributed on an "AS IS" BASIS,
171
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
172
+ See the License for the specific language governing permissions and
173
+ limitations under the License.
fujicv-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,254 @@
1
+ Metadata-Version: 2.4
2
+ Name: fujicv
3
+ Version: 1.0.0
4
+ Summary: Open-source Python package for image classification and regression built on timm + torchvision
5
+ Author: FujiCV Contributors
6
+ License: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/fujicv/fujicv
8
+ Project-URL: Repository, https://github.com/fujicv/fujicv
9
+ Project-URL: Bug Tracker, https://github.com/fujicv/fujicv/issues
10
+ Keywords: deep-learning,computer-vision,image-classification,timm,pytorch
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Science/Research
13
+ Classifier: License :: OSI Approved :: Apache Software License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.9
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
19
+ Requires-Python: >=3.9
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: torch>=2.0
23
+ Requires-Dist: torchvision>=0.15
24
+ Requires-Dist: timm>=0.9
25
+ Requires-Dist: albumentations>=1.3
26
+ Requires-Dist: scikit-learn>=1.3
27
+ Requires-Dist: matplotlib>=3.7
28
+ Requires-Dist: seaborn>=0.12
29
+ Requires-Dist: pandas>=2.0
30
+ Requires-Dist: pyyaml>=6.0
31
+ Requires-Dist: iterative-stratification>=0.1.7
32
+ Requires-Dist: numpy>=1.24
33
+ Requires-Dist: Pillow>=9.0
34
+ Requires-Dist: tqdm>=4.65
35
+ Provides-Extra: wandb
36
+ Requires-Dist: wandb>=0.15; extra == "wandb"
37
+ Provides-Extra: onnx
38
+ Requires-Dist: onnxruntime>=1.15; extra == "onnx"
39
+ Requires-Dist: onnx>=1.14; extra == "onnx"
40
+ Provides-Extra: dev
41
+ Requires-Dist: pytest>=7.4; extra == "dev"
42
+ Requires-Dist: pytest-cov>=4.1; extra == "dev"
43
+ Requires-Dist: ruff>=0.1; extra == "dev"
44
+ Requires-Dist: mypy>=1.5; extra == "dev"
45
+ Requires-Dist: detect-secrets>=1.4; extra == "dev"
46
+ Requires-Dist: types-PyYAML; extra == "dev"
47
+ Requires-Dist: types-seaborn; extra == "dev"
48
+ Provides-Extra: test
49
+ Requires-Dist: pytest>=7.4; extra == "test"
50
+ Requires-Dist: pytest-cov>=4.1; extra == "test"
51
+ Provides-Extra: all
52
+ Requires-Dist: fujicv[dev,onnx,wandb]; extra == "all"
53
+ Dynamic: license-file
54
+
55
+ # FujiCV
56
+
57
+ **Open-source Python package for image classification and regression, built on timm + torchvision.**
58
+
59
+ [![CI](https://github.com/fujicv/fujicv/actions/workflows/ci.yml/badge.svg)](https://github.com/fujicv/fujicv/actions)
60
+ [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
61
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green)](LICENSE)
62
+
63
+ ---
64
+
65
+ ## Features
66
+
67
+ - **Backbone factory** — instantly load any timm or torchvision model with a
68
+ single call; classifier head auto-stripped, output dimension auto-detected.
69
+ - **Task heads** — ClassificationHead, RegressionHead, MultiLabelHead.
70
+ - **Custom layers** — LinearBNDropout, GeM pooling, AttentionPool, SqueezeExcite.
71
+ - **ModelBuilder** — assemble backbone + custom layers + head; dummy forward
72
+ pass validates shapes at build time.
73
+ - **Albumentations pipelines** — light / medium / heavy augmentation presets,
74
+ ImageNet normalisation, deterministic val transforms.
75
+ - **CSVImageDataset** — reads any CSV-driven image dataset; pre-validates files,
76
+ skips missing with a warning; supports classification, regression, multilabel.
77
+ - **Loss functions** — 13 losses across classification, regression, and multilabel
78
+ tasks, all registered in `LOSS_REGISTRY`.
79
+ - **Metrics** — 16 metrics across all tasks, registered in `METRIC_REGISTRY`.
80
+ - **Trainer** — AMP, gradient clipping, early stopping, best/last checkpointing,
81
+ history CSV.
82
+ - **WandbLogger** — W&B integration via env-var only (`WANDB_API_KEY`); graceful
83
+ no-op when W&B is absent.
84
+ - **Evaluation** — confusion matrix, ROC/PR curves, t-SNE, Grad-CAM (CNN),
85
+ attention rollout (ViT).
86
+ - **Inference** — `Predictor.from_checkpoint` for single image and batch inference.
87
+ - **ONNX export** — export and numeric verification.
88
+
89
+ ---
90
+
91
+ ## Installation
92
+
93
+ ```bash
94
+ # Core (CPU)
95
+ pip install fujicv
96
+
97
+ # With W&B logging
98
+ pip install "fujicv[wandb]"
99
+
100
+ # With ONNX export
101
+ pip install "fujicv[onnx]"
102
+
103
+ # Dev / testing
104
+ pip install "fujicv[dev]"
105
+ ```
106
+
107
+ > **PyTorch is not included as a transitive dependency on PyPI.**
108
+ > Install it separately following the [official instructions](https://pytorch.org/get-started/locally/)
109
+ > to pick the right CUDA version.
110
+
111
+ ---
112
+
113
+ ## Quick Start
114
+
115
+ ### 1. Classification
116
+
117
+ ```python
118
+ from fujicv.models.builder import ModelBuilder
119
+ from fujicv.losses import get_loss
120
+ from fujicv.metrics import get_metric
121
+ from fujicv.engine.trainer import Trainer
122
+ from fujicv.data import build_splits, build_dataloaders
123
+ from fujicv.utils import load_config, set_seed
124
+
125
+ set_seed(42)
126
+ cfg = load_config("examples/configs/classification_example.yaml")
127
+
128
+ train_df, val_df, test_df = build_splits(cfg["dataset"])
129
+ train_loader, val_loader, _ = build_dataloaders(
130
+ train_df, val_df, test_df, cfg["dataset"], cfg["augmentation"]
131
+ )
132
+
133
+ model = ModelBuilder(
134
+ backbone_name="resnet50",
135
+ task="classification",
136
+ num_outputs=10,
137
+ pretrained=True,
138
+ ).build()
139
+
140
+ import torch.optim as optim
141
+
142
+ trainer = Trainer(
143
+ model=model,
144
+ train_loader=train_loader,
145
+ val_loader=val_loader,
146
+ loss_fn=get_loss("LabelSmoothingCE", {"smoothing": 0.1}),
147
+ metrics={"Accuracy": get_metric("Accuracy"), "F1": get_metric("F1")},
148
+ optimizer=optim.AdamW(model.parameters(), lr=3e-4),
149
+ epochs=30,
150
+ task="classification",
151
+ output_dir="outputs/",
152
+ )
153
+ history = trainer.train()
154
+ ```
155
+
156
+ ### 2. Using the example scripts
157
+
158
+ ```bash
159
+ # Train
160
+ python examples/train.py --config examples/configs/classification_example.yaml
161
+
162
+ # Evaluate (with attention maps)
163
+ python examples/evaluate.py \
164
+ --config examples/configs/classification_example.yaml \
165
+ --checkpoint outputs/classification/best.pt \
166
+ --with-attention-maps
167
+ ```
168
+
169
+ ### 3. Inference
170
+
171
+ ```python
172
+ from fujicv.inference import Predictor
173
+ from fujicv.models.builder import ModelBuilder
174
+
175
+ model_skeleton = ModelBuilder(
176
+ backbone_name="resnet50", task="classification", num_outputs=10, pretrained=False
177
+ ).build()
178
+
179
+ predictor = Predictor.from_checkpoint("outputs/classification/best.pt", model=model_skeleton)
180
+ label, confidence = predictor.predict("path/to/image.jpg")
181
+ print(f"Predicted: {label} ({confidence:.1%})")
182
+ ```
183
+
184
+ ### 4. ONNX Export
185
+
186
+ ```python
187
+ from fujicv.export import to_onnx, verify_onnx
188
+
189
+ to_onnx(model, "model.onnx")
190
+ verify_onnx(model, "model.onnx")
191
+ ```
192
+
193
+ ---
194
+
195
+ ## Package Layout
196
+
197
+ ```
198
+ fujicv/
199
+ models/ backbone factory, heads, custom layers, ModelBuilder
200
+ data/ CSVImageDataset, transforms, dataloader factory
201
+ losses/ 13 loss functions + registry
202
+ metrics/ 16 metric callables + registry
203
+ engine/ Trainer, WandbLogger, callbacks
204
+ eval/ plots, report, ROC/PR curves, t-SNE, attention maps
205
+ utils/ Registry, set_seed, config loader
206
+ inference/ Predictor
207
+ export/ ONNX export & verification
208
+ tests/
209
+ examples/
210
+ configs/ YAML configs for each task type
211
+ train.py
212
+ evaluate.py
213
+ ```
214
+
215
+ ---
216
+
217
+ ## Supported Tasks
218
+
219
+ | Task | Loss examples | Metric examples |
220
+ |------|--------------|----------------|
221
+ | Classification / Multiclass | CrossEntropyLoss, FocalLoss, LabelSmoothingCE | Accuracy, F1, AUROC |
222
+ | Regression | MSELoss, HuberLoss, QuantileLoss | MAE, RMSE, R2Score |
223
+ | Multi-label | BCEWithLogitsLoss, AsymmetricLoss, FocalBCELoss | HammingLoss, mAP, PerLabelAUROC |
224
+
225
+ ---
226
+
227
+ ## Security
228
+
229
+ See [SECURITY.md](SECURITY.md) for the full policy. Key points:
230
+
231
+ - No hardcoded credentials anywhere in the codebase.
232
+ - W&B API key read from `WANDB_API_KEY` environment variable only.
233
+ - Loss/metric functions are pure tensor operations with no network calls.
234
+
235
+ ---
236
+
237
+ ## Contributing
238
+
239
+ 1. Fork the repository and create a feature branch.
240
+ 2. Install in editable mode: `pip install -e ".[dev]"`
241
+ 3. Run the checks locally:
242
+ ```bash
243
+ ruff check fujicv/ tests/
244
+ mypy fujicv/
245
+ pytest tests/
246
+ detect-secrets scan
247
+ ```
248
+ 4. Open a pull request — CI will run automatically.
249
+
250
+ ---
251
+
252
+ ## License
253
+
254
+ [MIT](LICENSE) — Copyright (c) 2024 FujiCV Contributors.
fujicv-1.0.0/README.md ADDED
@@ -0,0 +1,200 @@
1
+ # FujiCV
2
+
3
+ **Open-source Python package for image classification and regression, built on timm + torchvision.**
4
+
5
+ [![CI](https://github.com/fujicv/fujicv/actions/workflows/ci.yml/badge.svg)](https://github.com/fujicv/fujicv/actions)
6
+ [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green)](LICENSE)
8
+
9
+ ---
10
+
11
+ ## Features
12
+
13
+ - **Backbone factory** — instantly load any timm or torchvision model with a
14
+ single call; classifier head auto-stripped, output dimension auto-detected.
15
+ - **Task heads** — ClassificationHead, RegressionHead, MultiLabelHead.
16
+ - **Custom layers** — LinearBNDropout, GeM pooling, AttentionPool, SqueezeExcite.
17
+ - **ModelBuilder** — assemble backbone + custom layers + head; dummy forward
18
+ pass validates shapes at build time.
19
+ - **Albumentations pipelines** — light / medium / heavy augmentation presets,
20
+ ImageNet normalisation, deterministic val transforms.
21
+ - **CSVImageDataset** — reads any CSV-driven image dataset; pre-validates files,
22
+ skips missing with a warning; supports classification, regression, multilabel.
23
+ - **Loss functions** — 13 losses across classification, regression, and multilabel
24
+ tasks, all registered in `LOSS_REGISTRY`.
25
+ - **Metrics** — 16 metrics across all tasks, registered in `METRIC_REGISTRY`.
26
+ - **Trainer** — AMP, gradient clipping, early stopping, best/last checkpointing,
27
+ history CSV.
28
+ - **WandbLogger** — W&B integration via env-var only (`WANDB_API_KEY`); graceful
29
+ no-op when W&B is absent.
30
+ - **Evaluation** — confusion matrix, ROC/PR curves, t-SNE, Grad-CAM (CNN),
31
+ attention rollout (ViT).
32
+ - **Inference** — `Predictor.from_checkpoint` for single image and batch inference.
33
+ - **ONNX export** — export and numeric verification.
34
+
35
+ ---
36
+
37
+ ## Installation
38
+
39
+ ```bash
40
+ # Core (CPU)
41
+ pip install fujicv
42
+
43
+ # With W&B logging
44
+ pip install "fujicv[wandb]"
45
+
46
+ # With ONNX export
47
+ pip install "fujicv[onnx]"
48
+
49
+ # Dev / testing
50
+ pip install "fujicv[dev]"
51
+ ```
52
+
53
+ > **PyTorch is not included as a transitive dependency on PyPI.**
54
+ > Install it separately following the [official instructions](https://pytorch.org/get-started/locally/)
55
+ > to pick the right CUDA version.
56
+
57
+ ---
58
+
59
+ ## Quick Start
60
+
61
+ ### 1. Classification
62
+
63
+ ```python
64
+ from fujicv.models.builder import ModelBuilder
65
+ from fujicv.losses import get_loss
66
+ from fujicv.metrics import get_metric
67
+ from fujicv.engine.trainer import Trainer
68
+ from fujicv.data import build_splits, build_dataloaders
69
+ from fujicv.utils import load_config, set_seed
70
+
71
+ set_seed(42)
72
+ cfg = load_config("examples/configs/classification_example.yaml")
73
+
74
+ train_df, val_df, test_df = build_splits(cfg["dataset"])
75
+ train_loader, val_loader, _ = build_dataloaders(
76
+ train_df, val_df, test_df, cfg["dataset"], cfg["augmentation"]
77
+ )
78
+
79
+ model = ModelBuilder(
80
+ backbone_name="resnet50",
81
+ task="classification",
82
+ num_outputs=10,
83
+ pretrained=True,
84
+ ).build()
85
+
86
+ import torch.optim as optim
87
+
88
+ trainer = Trainer(
89
+ model=model,
90
+ train_loader=train_loader,
91
+ val_loader=val_loader,
92
+ loss_fn=get_loss("LabelSmoothingCE", {"smoothing": 0.1}),
93
+ metrics={"Accuracy": get_metric("Accuracy"), "F1": get_metric("F1")},
94
+ optimizer=optim.AdamW(model.parameters(), lr=3e-4),
95
+ epochs=30,
96
+ task="classification",
97
+ output_dir="outputs/",
98
+ )
99
+ history = trainer.train()
100
+ ```
101
+
102
+ ### 2. Using the example scripts
103
+
104
+ ```bash
105
+ # Train
106
+ python examples/train.py --config examples/configs/classification_example.yaml
107
+
108
+ # Evaluate (with attention maps)
109
+ python examples/evaluate.py \
110
+ --config examples/configs/classification_example.yaml \
111
+ --checkpoint outputs/classification/best.pt \
112
+ --with-attention-maps
113
+ ```
114
+
115
+ ### 3. Inference
116
+
117
+ ```python
118
+ from fujicv.inference import Predictor
119
+ from fujicv.models.builder import ModelBuilder
120
+
121
+ model_skeleton = ModelBuilder(
122
+ backbone_name="resnet50", task="classification", num_outputs=10, pretrained=False
123
+ ).build()
124
+
125
+ predictor = Predictor.from_checkpoint("outputs/classification/best.pt", model=model_skeleton)
126
+ label, confidence = predictor.predict("path/to/image.jpg")
127
+ print(f"Predicted: {label} ({confidence:.1%})")
128
+ ```
129
+
130
+ ### 4. ONNX Export
131
+
132
+ ```python
133
+ from fujicv.export import to_onnx, verify_onnx
134
+
135
+ to_onnx(model, "model.onnx")
136
+ verify_onnx(model, "model.onnx")
137
+ ```
138
+
139
+ ---
140
+
141
+ ## Package Layout
142
+
143
+ ```
144
+ fujicv/
145
+ models/ backbone factory, heads, custom layers, ModelBuilder
146
+ data/ CSVImageDataset, transforms, dataloader factory
147
+ losses/ 13 loss functions + registry
148
+ metrics/ 16 metric callables + registry
149
+ engine/ Trainer, WandbLogger, callbacks
150
+ eval/ plots, report, ROC/PR curves, t-SNE, attention maps
151
+ utils/ Registry, set_seed, config loader
152
+ inference/ Predictor
153
+ export/ ONNX export & verification
154
+ tests/
155
+ examples/
156
+ configs/ YAML configs for each task type
157
+ train.py
158
+ evaluate.py
159
+ ```
160
+
161
+ ---
162
+
163
+ ## Supported Tasks
164
+
165
+ | Task | Loss examples | Metric examples |
166
+ |------|--------------|----------------|
167
+ | Classification / Multiclass | CrossEntropyLoss, FocalLoss, LabelSmoothingCE | Accuracy, F1, AUROC |
168
+ | Regression | MSELoss, HuberLoss, QuantileLoss | MAE, RMSE, R2Score |
169
+ | Multi-label | BCEWithLogitsLoss, AsymmetricLoss, FocalBCELoss | HammingLoss, mAP, PerLabelAUROC |
170
+
171
+ ---
172
+
173
+ ## Security
174
+
175
+ See [SECURITY.md](SECURITY.md) for the full policy. Key points:
176
+
177
+ - No hardcoded credentials anywhere in the codebase.
178
+ - W&B API key read from `WANDB_API_KEY` environment variable only.
179
+ - Loss/metric functions are pure tensor operations with no network calls.
180
+
181
+ ---
182
+
183
+ ## Contributing
184
+
185
+ 1. Fork the repository and create a feature branch.
186
+ 2. Install in editable mode: `pip install -e ".[dev]"`
187
+ 3. Run the checks locally:
188
+ ```bash
189
+ ruff check fujicv/ tests/
190
+ mypy fujicv/
191
+ pytest tests/
192
+ detect-secrets scan
193
+ ```
194
+ 4. Open a pull request — CI will run automatically.
195
+
196
+ ---
197
+
198
+ ## License
199
+
200
+ [MIT](LICENSE) — Copyright (c) 2024 FujiCV Contributors.
@@ -0,0 +1,10 @@
1
+ """FujiCV — image classification and regression built on timm + torchvision."""
2
+
3
+ __version__ = "1.0.0"
4
+ __author__ = "FujiCV Contributors"
5
+
6
+ from fujicv.data.datasets import get_default_dataset # noqa: F401
7
+ from fujicv.utils.registry import Registry # noqa: F401
8
+ from fujicv.utils.seed import get_device, set_seed # noqa: F401
9
+
10
+ __all__ = ["__version__", "__author__", "get_device", "set_seed", "get_default_dataset"]
@@ -0,0 +1,13 @@
1
+ """Data loading, splitting, and augmentation."""
2
+
3
+ from fujicv.data.dataloader import build_dataloaders
4
+ from fujicv.data.datasets import CSVImageDataset, build_splits
5
+ from fujicv.data.transforms import get_train_transforms, get_val_transforms
6
+
7
+ __all__ = [
8
+ "CSVImageDataset",
9
+ "build_splits",
10
+ "build_dataloaders",
11
+ "get_train_transforms",
12
+ "get_val_transforms",
13
+ ]