fotonet 0.1.0a0__tar.gz

fotonet-0.1.0a0/MANIFEST.in

@@ -0,0 +1,13 @@
+include README.md
+include pyproject.toml
+recursive-include docs *.md
+recursive-include examples *.py *.md
+recursive-include fotonet/config *.yaml
+recursive-exclude datasets *
+recursive-exclude dev-tools *
+recursive-exclude docs/superpowers *
+exclude examples/compare_fotonet_yolo_gt.py
+recursive-exclude tests *
+recursive-exclude logs *
+recursive-exclude runs *
+global-exclude __pycache__ *.py[cod] *.pt *.pth *.onnx *.engine *.torchscript *.metadata.json

fotonet-0.1.0a0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: fotonet
+Version: 0.1.0a0
+Summary: Lightweight NMS-free object detection with an Ultralytics-like API.
+Author: FOTO-NET contributors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/serionn/fotonet
+Project-URL: Documentation, https://github.com/serionn/fotonet#readme
+Project-URL: Source, https://github.com/serionn/fotonet
+Keywords: object-detection,computer-vision,deep-learning,fotonet
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.23
+Requires-Dist: pillow>=9.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: opencv-python>=4.7
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: scipy>=1.10
+Requires-Dist: tqdm>=4.64
+Provides-Extra: metrics
+Requires-Dist: pycocotools>=2.0.7; extra == "metrics"
+Provides-Extra: export
+Requires-Dist: onnx>=1.14; extra == "export"
+Requires-Dist: onnxsim>=0.4.36; extra == "export"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+
+![FOTO-NET alpha banner](https://raw.githubusercontent.com/hazegreleases/boringstuffreally/main/Alpha%20banner.png)
+
+# FOTO-NET
+
+FOTO-NET is a lightweight NMS-free object detector with an Ultralytics-like Python API and an application-friendly transform layer for working with detection boxes.
+
+This is the alpha release, everything is subject to change. Not recommended for production workflows, just a demo of what is coming.
+
+## What It Is
+
+FOTO-NET focuses on practical object detection:
+
+- compact model scales
+- NMS-free one-to-one inference
+- optional one-to-many training supervision
+- small-object friendly P2 variants
+- direct Python results objects
+- transform helpers for crops, anchors, pixel movement, containment, and box manipulation
+- export paths for ONNX, TorchScript, TensorRT, and CoreML where dependencies are available
+
+## Alpha Status
+
+The alpha release is intended for experimentation, training runs, integration tests, and feedback. The core Python API, training path, inference path, transform API, and ONNX export should be usable. CoreML export code exists, but it should not be treated as certified until fresh platform-specific verification is published.
+
+## Install
+
+```bash
+git clone https://github.com/hazegreleases/fotonet.git
+cd fotonet
+python -m pip install torch torchvision numpy pillow pyyaml opencv-python matplotlib scipy tqdm
+```
+
+## Quick Start
+
+```python
+from fotonet import FOTONET
+
+model = FOTONET("fotonetn")
+results = model.predict("image.jpg", conf=0.25)
+
+for box in results.boxes:
+    print(box.cls, box.conf, box.xyxy)
+```
+
+CLI:
+
+```bash
+python -m fotonet.cli.main predict model=fotonet-n source=image.jpg conf=0.25 save=true
+```
+
+## Transform API
+
+```python
+from fotonet import AnchorPoint
+
+box = results.boxes[0]
+crop = (
+    box.transform
+    .setAnchor(AnchorPoint.CENTER)
+    .pixelExpand(40)
+    .clamp()
+    .crop(results.orig_img)
+)
+```
+
+The raw box formats remain available through `box.xywh`, `box.xyxy`, and `results.boxes.numpy()`.
+
+## Training
+
+FOTO-NET expects YOLO-format labels:
+
+```text
+class_id x_center y_center width height
+```
+
+Train through Python:
+
+```python
+from fotonet import FOTONET
+
+model = FOTONET("fotonetn")
+model.train(data="data.yaml", epochs=100, imgsz=640, batch=16)
+```
+
+Train through CLI:
+
+```bash
+fotonet train model=fotonetn data=data.yaml epochs=100 imgsz=640 batch=16
+```
+
+## Export
+
+```python
+from fotonet import FOTONET
+
+model = FOTONET("fotonet-n")
+model.export(format="onnx", path="dev-tools/runs/fotonet.onnx", imgsz=640)
+```
+
+## Model Weights
+
+The alpha repository includes `fotonet-n` as the public nano checkpoint. Training outputs and development weights live outside the public surface.
+
+## Alpha Checkpoint Metrics
+
+`fotonet-n` is the alpha nano checkpoint included in this repository.
+
+| Checkpoint | mAP@.50:.95 | Parameters | MACs at 640 | GFLOPs at 640 |
+|---|---:|---:|---:|---:|
+| `fotonet-n` | 22.68% | 2.75M | 2.43G | 4.85G |
+
+Inference times are not out yet because the benchmark computer is IO bottlenecked, so the timing numbers are not reliable enough to publish.
+
+## Documentation
+
+- Installation: `docs/installation.md`
+- Quick start: `docs/quickstart.md`
+- Inference: `docs/inference.md`
+- Training: `docs/training.md`
+- Export: `docs/export.md`
+- Transform API: `docs/transform-api.md`
+- Model zoo: `docs/model-zoo.md`
+
+## License
+
+FOTO-NET is licensed under the Apache License, Version 2.0.

fotonet-0.1.0a0/README.md

@@ -0,0 +1,126 @@
+![FOTO-NET alpha banner](https://raw.githubusercontent.com/hazegreleases/boringstuffreally/main/Alpha%20banner.png)
+
+# FOTO-NET
+
+FOTO-NET is a lightweight NMS-free object detector with an Ultralytics-like Python API and an application-friendly transform layer for working with detection boxes.
+
+This is the alpha release, everything is subject to change. Not recommended for production workflows, just a demo of what is coming.
+
+## What It Is
+
+FOTO-NET focuses on practical object detection:
+
+- compact model scales
+- NMS-free one-to-one inference
+- optional one-to-many training supervision
+- small-object friendly P2 variants
+- direct Python results objects
+- transform helpers for crops, anchors, pixel movement, containment, and box manipulation
+- export paths for ONNX, TorchScript, TensorRT, and CoreML where dependencies are available
+
+## Alpha Status
+
+The alpha release is intended for experimentation, training runs, integration tests, and feedback. The core Python API, training path, inference path, transform API, and ONNX export should be usable. CoreML export code exists, but it should not be treated as certified until fresh platform-specific verification is published.
+
+## Install
+
+```bash
+git clone https://github.com/hazegreleases/fotonet.git
+cd fotonet
+python -m pip install torch torchvision numpy pillow pyyaml opencv-python matplotlib scipy tqdm
+```
+
+## Quick Start
+
+```python
+from fotonet import FOTONET
+
+model = FOTONET("fotonetn")
+results = model.predict("image.jpg", conf=0.25)
+
+for box in results.boxes:
+    print(box.cls, box.conf, box.xyxy)
+```
+
+CLI:
+
+```bash
+python -m fotonet.cli.main predict model=fotonet-n source=image.jpg conf=0.25 save=true
+```
+
+## Transform API
+
+```python
+from fotonet import AnchorPoint
+
+box = results.boxes[0]
+crop = (
+    box.transform
+    .setAnchor(AnchorPoint.CENTER)
+    .pixelExpand(40)
+    .clamp()
+    .crop(results.orig_img)
+)
+```
+
+The raw box formats remain available through `box.xywh`, `box.xyxy`, and `results.boxes.numpy()`.
+
+## Training
+
+FOTO-NET expects YOLO-format labels:
+
+```text
+class_id x_center y_center width height
+```
+
+Train through Python:
+
+```python
+from fotonet import FOTONET
+
+model = FOTONET("fotonetn")
+model.train(data="data.yaml", epochs=100, imgsz=640, batch=16)
+```
+
+Train through CLI:
+
+```bash
+fotonet train model=fotonetn data=data.yaml epochs=100 imgsz=640 batch=16
+```
+
+## Export
+
+```python
+from fotonet import FOTONET
+
+model = FOTONET("fotonet-n")
+model.export(format="onnx", path="dev-tools/runs/fotonet.onnx", imgsz=640)
+```
+
+## Model Weights
+
+The alpha repository includes `fotonet-n` as the public nano checkpoint. Training outputs and development weights live outside the public surface.
+
+## Alpha Checkpoint Metrics
+
+`fotonet-n` is the alpha nano checkpoint included in this repository.
+
+| Checkpoint | mAP@.50:.95 | Parameters | MACs at 640 | GFLOPs at 640 |
+|---|---:|---:|---:|---:|
+| `fotonet-n` | 22.68% | 2.75M | 2.43G | 4.85G |
+
+Inference times are not out yet because the benchmark computer is IO bottlenecked, so the timing numbers are not reliable enough to publish.
+
+## Documentation
+
+- Installation: `docs/installation.md`
+- Quick start: `docs/quickstart.md`
+- Inference: `docs/inference.md`
+- Training: `docs/training.md`
+- Export: `docs/export.md`
+- Transform API: `docs/transform-api.md`
+- Model zoo: `docs/model-zoo.md`
+
+## License
+
+FOTO-NET is licensed under the Apache License, Version 2.0.

fotonet-0.1.0a0/docs/contributing.md

@@ -0,0 +1,13 @@
+# Contributing
+
+Use small focused pull requests.
+
+Run the test suite before submitting:
+
+```bash
+python -m unittest discover -s tests -p "test_*.py"
+```
+
+Keep public docs free of local absolute paths.
+
+Do not commit datasets, checkpoints, logs, or exported engines.

fotonet-0.1.0a0/docs/export.md

@@ -0,0 +1,36 @@
+# Export
+
+FOTO-NET alpha provides export helpers for inference graphs. Export support depends on the local toolchain.
+
+## ONNX
+
+```python
+from fotonet import FOTONET
+
+model = FOTONET("fotonet-n")
+model.export(format="onnx", path="dev-tools/runs/fotonet.onnx", imgsz=640)
+```
+
+ONNX export writes a metadata JSON file next to the artifact.
+
+## TorchScript
+
+```python
+model.export(format="torchscript", path="fotonet.torchscript", imgsz=640)
+```
+
+## TensorRT
+
+TensorRT export requires `trtexec` in `PATH`.
+
+```python
+model.export(format="tensorrt", path="fotonet.engine", imgsz=640, half=True)
+```
+
+## CoreML
+
+CoreML code exists, but this alpha does not treat CoreML as certified unless a fresh platform-specific verification is published.
+
+## Output Format
+
+Exported graphs output the raw one-to-one inference tensor. Application code is responsible for postprocessing unless a future release adds packaged postprocess graphs.

fotonet-0.1.0a0/docs/inference.md

@@ -0,0 +1,63 @@
+# Inference
+
+## Python Inference
+
+```python
+from fotonet import FOTONET
+
+model = FOTONET("fotonet-n")
+results = model.predict("image.jpg", conf=0.25, imgsz=640)
+```
+
+## Folder Inference
+
+```python
+from fotonet import FOTONET
+
+model = FOTONET("fotonet-n")
+results = model.predict("images", batch=8)
+for result in results:
+    print(result)
+```
+
+## BGR Frames
+
+OpenCV users can call `predict_bgr()` with BGR `uint8` frames:
+
+```python
+result = model.predict_bgr(frame, conf=0.25)
+```
+
+## Results Objects
+
+`Results` contains:
+
+- `orig_img`: original image object or array
+- `boxes`: iterable detection collection
+- `scores`: confidence tensor
+- `classes`: class id tensor
+- `names`: class name mapping
+
+Each `DetectionBox` exposes:
+
+- `idx`
+- `conf`
+- `cls_id`
+- `cls`
+- `xywh`
+- `xyxy`
+- `transform`
+
+## Visualization and Export Helpers
+
+```python
+plot = results.plot()
+results.save("dev-tools/runs/prediction.jpg")
+json_text = results.to_json()
+```
+
+`to_pandas()` requires pandas.
+
+## Inference Timing
+
+Inference times are not out yet because the benchmark computer is IO bottlenecked, so the timing numbers are not reliable enough to publish.

fotonet-0.1.0a0/docs/installation.md

@@ -0,0 +1,55 @@
+# Installation
+
+## Requirements
+
+FOTO-NET alpha targets Python 3.10 or newer. A CUDA-capable PyTorch install is recommended for training, but CPU installs are useful for API tests, documentation examples, and small export smoke checks.
+
+Install PyTorch from the official PyTorch instructions for your platform first when you need a specific CUDA build.
+
+## Public Alpha Checkout
+
+```bash
+git clone https://github.com/hazegreleases/fotonet.git
+cd fotonet
+python -m pip install torch torchvision numpy pillow pyyaml opencv-python matplotlib scipy tqdm
+```
+
+Run Python examples from the repository root so the local `fotonet` package is importable.
+
+```bash
+python examples/transform_crop.py
+```
+
+## Optional ONNX Dependencies
+
+```bash
+python -m pip install onnx onnxsim
+```
+
+ONNX export works best when `onnx` is installed. `onnxsim` is optional and only used for graph simplification.
+
+## Optional Metrics Dependencies
+
+```bash
+python -m pip install pycocotools
+```
+
+`pycocotools` enables COCO-style validation metrics. Without it, FOTO-NET can still run model construction, inference, training code paths, and local tests that do not require COCO evaluation.
+
+## CUDA Notes
+
+Use a PyTorch build that matches your driver and CUDA runtime. Training speed depends heavily on GPU memory, batch size, image size, and whether validation is running on the full dataset.
+
+## Troubleshooting
+
+If imports fail after cloning, run:
+
+```bash
+python -c "from fotonet import FOTONET; print(FOTONET('fotonetn').nc)"
+```
+
+If export dependencies are missing, install them directly:
+
+```bash
+python -m pip install onnx onnxsim
+```

fotonet-0.1.0a0/docs/model-zoo.md

@@ -0,0 +1,28 @@
+# Model Zoo
+
+The alpha checkout includes the public nano checkpoint as `fotonet-n`.
+
+## Alpha Checkpoint
+
+| Checkpoint | Architecture | mAP@.50:.95 | Parameters | MACs at 640 | GFLOPs at 640 | Weights |
+|---|---|---:|---:|---:|---:|---|
+| `fotonet-n` | `fotonetn` | 22.68% | 2.75M | 2.43G | 4.85G | Included |
+
+The MACs and GFLOPs numbers are for a 640x640 input. GFLOPs are estimated as two FLOPs per MAC.
+
+Inference times are not out yet because the benchmark computer is IO bottlenecked, so the timing numbers are not reliable enough to publish.
+
+## Public Architectures
+
+| Name | Purpose | P2 | Quality Head | Status |
+|---|---|---|---|---|
+| `fotonetn` | Nano general detector | yes | yes | alpha checkpoint |
+| `fotonetn0` | Edge nano detector without P2 | no | no | alpha architecture |
+| `fotonets` | Small detector | yes | yes | alpha architecture |
+| `fotonetm` | Medium detector | yes | yes | alpha architecture |
+| `fotonetl` | Large detector | yes | yes | alpha architecture |
+| `fotonetx` | Extra-large detector | yes | yes | alpha architecture |
+
+## Development Weights
+
+Training checkpoints and comparison weights are development artifacts. Keep them out of the public surface.

fotonet-0.1.0a0/docs/quickstart.md

@@ -0,0 +1,42 @@
+# Quick Start
+
+This alpha release is a demo of what is coming. It is not recommended for production workflows.
+
+## Construct a Model
+
+```python
+from fotonet import FOTONET
+
+model = FOTONET("fotonetn")
+```
+
+Constructing a named scale builds the architecture. Released weights are needed for meaningful detections.
+
+## Run Inference With a Checkpoint
+
+```python
+from fotonet import FOTONET
+
+model = FOTONET("fotonet-n")
+results = model.predict("image.jpg", conf=0.25)
+print(results)
+```
+
+## Inspect Results
+
+```python
+for box in results.boxes:
+    print(box.cls, box.conf, box.xywh, box.xyxy)
+```
+
+## CLI Inference
+
+```bash
+python -m fotonet.cli.main predict model=fotonet-n source=image.jpg conf=0.25 save=true
+```
+
+## Train a YOLO Dataset
+
+```bash
+fotonet train model=fotonetn data=data.yaml epochs=100 imgsz=640 batch=16
+```

fotonet-0.1.0a0/docs/release-checklist.md

@@ -0,0 +1,16 @@
+# Alpha Release Checklist
+
+- [ ] Full tests pass on a clean clone.
+- [ ] README contains no emojis.
+- [ ] README hero image loads from the raw banner URL.
+- [ ] `.gitignore` excludes datasets, logs, weights, exports, and caches.
+- [ ] No local absolute paths appear in public docs or examples.
+- [ ] `python -m build` succeeds.
+- [ ] `twine check dist/*` succeeds.
+- [ ] Editable install works.
+- [ ] CLI help works.
+- [ ] At least one inference example runs.
+- [ ] At least one transform example runs.
+- [ ] Weights are attached to GitHub Releases, not committed.
+- [ ] SHA256 checksums are published for release weights.
+- [ ] GitHub release notes state alpha limitations.

fotonet-0.1.0a0/docs/security.md

@@ -0,0 +1,5 @@
+# Security
+
+Report security issues through private GitHub security advisories when available.
+
+Do not open public issues for vulnerabilities involving model loading, filesystem access, or exported artifact execution.

fotonet-0.1.0a0/docs/training.md

@@ -0,0 +1,53 @@
+# Training
+
+This alpha release is not recommended for production workflows. The training path exists so users can experiment, reproduce runs, and help harden the project.
+
+## Dataset Format
+
+FOTO-NET expects YOLO-format labels:
+
+```text
+class_id x_center y_center width height
+```
+
+Coordinates are normalized to the image size.
+
+## `data.yaml`
+
+A minimal dataset config should include:
+
+```yaml
+path: /path/to/dataset
+train: images/train
+val: images/val
+nc: 80
+names:
+  0: class_0
+```
+
+Use paths that are valid on your machine. Do not commit local dataset paths to shared configs.
+
+## Python Training
+
+```python
+from fotonet import FOTONET
+
+model = FOTONET("fotonetn")
+model.train(data="data.yaml", epochs=100, imgsz=640, batch=16)
+```
+
+## CLI Training
+
+```bash
+fotonet train model=fotonetn data=data.yaml epochs=100 imgsz=640 batch=16
+```
+
+## Resume and Pretrained Modes
+
+`resume=True` means continue from a full training checkpoint such as `fotonet_last.pt`. It restores training state, optimizer state, scheduler state, scaler state, and epoch position.
+
+`pretrained=True` means load model weights only and start with a fresh optimizer and scheduler.
+
+`resume=True` and `pretrained=True` are mutually exclusive.
+
+`fotonet_best.pt` can be a slim inference checkpoint. `fotonet_last.pt` is the resumable training checkpoint.

fotonet-0.1.0a0/docs/transform-api.md

@@ -0,0 +1,64 @@
+# Transform API
+
+The transform API is a mutable spatial helper attached to each detection box.
+
+Read `box.xywh` for the original detection center and size. Use `box.transform` for working spatial operations such as cropping, moving, expanding, anchoring, and containment checks.
+
+## Basic Usage
+
+```python
+from fotonet import AnchorPoint
+
+box = results.boxes[0]
+crop = (
+    box.transform
+    .setAnchor(AnchorPoint.CENTER)
+    .pixelExpand(40)
+    .clamp()
+    .crop(results.orig_img)
+)
+```
+
+## Properties
+
+- `box.transform.xywh`: normalized center x, center y, width, height
+- `box.transform.xyxy`: normalized x1, y1, x2, y2
+- `position`: normalized anchor position
+- `pixelPosition`: anchor position in pixels
+- `size`: normalized width and height
+- `pixelSize`: width and height in pixels
+- `corner[index]`: normalized corner point, 1 through 4
+- `side[index]`: normalized side midpoint, 1 through 4
+
+## Methods
+
+- `setAnchor(anchor)`: set the anchor used by scale and expansion operations
+- `move((dx, dy))`: move in normalized units
+- `pixelMove((dx, dy))`: move in pixels
+- `scale((sx, sy))`: scale about the active anchor
+- `expand(padding)`: expand in normalized units
+- `pixelExpand(padding)`: expand in pixels
+- `clamp()`: clamp the box to image bounds
+- `setBox(mode=1)`: make the region square
+- `setAspectRatio((w, h), mode=1)`: enforce an aspect ratio
+- `crop(image)`: crop from a PIL image or NumPy array
+- `contains(point=...)`: normalized point or region containment
+- `pixelContains(point=...)`: pixel point or region containment
+- `iou(other)`: intersection over union
+- `distance(point)`: normalized distance from active anchor
+- `focus(x, y, w, h)`: focus on a relative subregion
+- `focusReset()`: restore the original detection box
+
+## Anchors
+
+Available anchors include:
+
+- `AnchorPoint.CENTER`
+- `AnchorPoint.TOP_LEFT`
+- `AnchorPoint.TOP_RIGHT`
+- `AnchorPoint.BOTTOM_LEFT`
+- `AnchorPoint.BOTTOM_RIGHT`
+- `AnchorPoint.TOP`
+- `AnchorPoint.BOTTOM`
+- `AnchorPoint.LEFT`
+- `AnchorPoint.RIGHT`