Computer-Vision-Assistant-Package 1.0__tar.gz

computer_vision_assistant_package-1.0/License.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shounak Sanyal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE

computer_vision_assistant_package-1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: Computer_Vision_Assistant_Package
+Version: 1.0
+Summary: A user friendly package assiting in the most common computer vision tasks
+Author-email: Shounak Sanyal <shounaksanyal1902@outlook.com>
+License-Expression: MIT
+License-File: License.txt
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Computer_vision_assisting_tools
+
+**Author:** Shounak Sanyal
+
+A small toolbox of helpers for computer-vision projects. It bundles the
+functions that were most useful in a detection + classification workflow:
+
+* find images and annotation files in a folder tree,
+* check and read COCO-style datasets,
+* run a detector (RF-DETR, YOLO) or a CNN classifier on an image and draw the
+  predictions next to the ground truth,
+* slice large images into tiles (SAHI) and run detection / classification on
+  every tile,
+* pre-process images (CLAHE, Reinhard colour transfer, Otsu, augmentation,
+  square padding, tensor transforms),
+* score a detector with IoU, precision / recall and mAP.
+
+---
+
+## Package hierarchy
+
+```
+.
+├── README.md
+└── Computer_vision_assisting_tools/
+    ├── __innit__.py        Package docstring (no code)
+    ├── AI_Metrics.py       Detection metrics
+    │   ├── IOU_calc
+    │   ├── mAP_calc
+    │   ├── AUC_calc
+    │   └── detection_metrics
+    ├── Basic_Utils.py      Files, datasets, annotations, inference, SAHI
+    │   ├── IMAGE_EXTENSIONS            (constant)
+    │   ├── img_loc
+    │   ├── ai_analytics
+    │   ├── dataset_check
+    │   ├── provide_annotations
+    │   ├── SAHI_generation
+    │   └── SAHI_analysis
+    └── Image_Utils.py      Image pre-processing
+        ├── image_processing
+        ├── data_augmentation
+        ├── cell_geometry
+        └── cell_transform
+```
+
+### How the modules depend on each other
+
+```
+AI_Metrics.py  ──►  Basic_Utils.py  ──►  Image_Utils.py
+ (metrics)           (data + models)      (image helpers)
+```
+
+`AI_Metrics` uses `provide_annotations` and `ai_analytics` from `Basic_Utils`;
+`Basic_Utils` uses `cell_geometry` and `cell_transform` from `Image_Utils`.
+`Image_Utils` depends on none of the others. The modules import each other
+with relative imports (`from .Basic_Utils import *`), so they must be used as
+part of the package, not run directly as scripts.
+
+---
+
+## Module descriptions
+
+### `Image_Utils.py` — image pre-processing
+
+Helpers that prepare images (for example single-cell crops) before they reach
+a classifier. Images are NumPy arrays read with OpenCV, so colour images are in
+BGR order unless stated otherwise.
+
+| Function | What it does |
+|---|---|
+| `image_processing(img, ref_img=None, normalisation='Clahe', grid_window=(8,8))` | Normalises an image with CLAHE (default), Reinhard colour transfer (needs `ref_img`) or Otsu thresholding (`'Otsu'`). |
+| `data_augmentation(img, n_rotate=3, blur=True)` | Returns up to three rotated copies (90°, 180°, 270°; default 3) and, optionally, a Gaussian-blurred copy. |
+| `cell_geometry(img)` | Makes both sides even, then pads the shorter side with black so the image becomes a centred square. |
+| `cell_transform(img, key)` | Converts an image to a `float32` tensor. `key=0` adds ImageNet normalisation, `key=1` only scales to [0, 1]. |
+
+### `Basic_Utils.py` — data, annotations, inference and SAHI
+
+The main working module. It finds files, checks datasets, reads ground truth,
+runs models and handles SAHI tiling.
+
+| Function | What it does |
+|---|---|
+| `IMAGE_EXTENSIONS` | Tuple of file extensions treated as images (case-insensitive). |
+| `img_loc(path)` | Recursively lists image, `.json` and `.txt` files under a folder. Returns `(img_list, json_list, txt_list)`. |
+| `ai_analytics(file, image_path, model, name='RFDETR', key=True, mode='Detection')` | Runs RF-DETR / YOLO detection or CNN classification on one image (the model is moved to the GPU if available). For detection it also reads the COCO ground truth and can draw predictions (blue) and ground truth (green). |
+| `dataset_check(file)` | Checks that the images in a folder and the COCO json agree. Returns five counts (images, json images, annotated images, categories, used categories). |
+| `provide_annotations(json_path, file_name, key='COCO')` | Returns the ground-truth boxes and labels for one image, from a COCO json or from the `'Vanila'` multi-json format. |
+| `SAHI_generation(image_path, ...)` | Slices a large image into tiles and saves them (the output folder is deleted first if it exists). |
+| `SAHI_analysis(image_path, model_det, model_clss=None, ...)` | Detects (and optionally classifies) objects on every tile and draws them on the full image. |
+
+### `AI_Metrics.py` — detection metrics
+
+Scores a detector on a single image against COCO ground truth. Boxes are in
+`(x_min, y_min, x_max, y_max)` format.
+
+| Function | What it does |
+|---|---|
+| `IOU_calc(target_pts, gt_pts)` | IoU of one box against a list of ground-truth boxes. |
+| `mAP_calc(bboxes, gt_bboxes)` | Running precision and recall for IoU thresholds 0.50 – 0.90. |
+| `AUC_calc(precision, recall)` | Builds the smoothed precision curve used for the area under the curve. |
+| `detection_metrics(json_file, img_file, model_test)` | End-to-end evaluation. Returns `(mAP_50, mAP_50_95)`. |
+
+---
+
+## Requirements
+
+* Python 3.9+
+* `numpy`
+* `opencv-python`
+* `torch`
+* `torchvision` (0.16 or newer, for `torchvision.transforms.v2.ToImage`)
+* `matplotlib` (imported by the modules)
+* `sahi`
+* A detector with a `.predict()` method (RF-DETR or Ultralytics YOLO) if you
+  use `ai_analytics`, `SAHI_analysis` or `detection_metrics`.
+
+## Quick example
+
+```python
+from Computer_vision_assisting_tools.Basic_Utils import img_loc, dataset_check
+from Computer_vision_assisting_tools.Image_Utils import image_processing
+
+images, jsons, txts = img_loc("my_dataset")      # find all files
+print(dataset_check("my_dataset"))               # sanity-check images vs json
+
+import cv2
+img = cv2.imread(images[0])
+img_clahe = image_processing(img, normalisation="Clahe")
+```
+
+## Documentation style
+
+Every module, function and inner helper has a NumPy-style docstring
+(`Parameters`, `Returns`, `Examples`). Use `help(function_name)` to read
+them.
+
+## Author
+
+Created and maintained by **Shounak Sanyal**.

computer_vision_assistant_package-1.0/README.md

@@ -0,0 +1,140 @@
+# Computer_vision_assisting_tools
+
+**Author:** Shounak Sanyal
+
+A small toolbox of helpers for computer-vision projects. It bundles the
+functions that were most useful in a detection + classification workflow:
+
+* find images and annotation files in a folder tree,
+* check and read COCO-style datasets,
+* run a detector (RF-DETR, YOLO) or a CNN classifier on an image and draw the
+  predictions next to the ground truth,
+* slice large images into tiles (SAHI) and run detection / classification on
+  every tile,
+* pre-process images (CLAHE, Reinhard colour transfer, Otsu, augmentation,
+  square padding, tensor transforms),
+* score a detector with IoU, precision / recall and mAP.
+
+---
+
+## Package hierarchy
+
+```
+.
+├── README.md
+└── Computer_vision_assisting_tools/
+    ├── __innit__.py        Package docstring (no code)
+    ├── AI_Metrics.py       Detection metrics
+    │   ├── IOU_calc
+    │   ├── mAP_calc
+    │   ├── AUC_calc
+    │   └── detection_metrics
+    ├── Basic_Utils.py      Files, datasets, annotations, inference, SAHI
+    │   ├── IMAGE_EXTENSIONS            (constant)
+    │   ├── img_loc
+    │   ├── ai_analytics
+    │   ├── dataset_check
+    │   ├── provide_annotations
+    │   ├── SAHI_generation
+    │   └── SAHI_analysis
+    └── Image_Utils.py      Image pre-processing
+        ├── image_processing
+        ├── data_augmentation
+        ├── cell_geometry
+        └── cell_transform
+```
+
+### How the modules depend on each other
+
+```
+AI_Metrics.py  ──►  Basic_Utils.py  ──►  Image_Utils.py
+ (metrics)           (data + models)      (image helpers)
+```
+
+`AI_Metrics` uses `provide_annotations` and `ai_analytics` from `Basic_Utils`;
+`Basic_Utils` uses `cell_geometry` and `cell_transform` from `Image_Utils`.
+`Image_Utils` depends on none of the others. The modules import each other
+with relative imports (`from .Basic_Utils import *`), so they must be used as
+part of the package, not run directly as scripts.
+
+---
+
+## Module descriptions
+
+### `Image_Utils.py` — image pre-processing
+
+Helpers that prepare images (for example single-cell crops) before they reach
+a classifier. Images are NumPy arrays read with OpenCV, so colour images are in
+BGR order unless stated otherwise.
+
+| Function | What it does |
+|---|---|
+| `image_processing(img, ref_img=None, normalisation='Clahe', grid_window=(8,8))` | Normalises an image with CLAHE (default), Reinhard colour transfer (needs `ref_img`) or Otsu thresholding (`'Otsu'`). |
+| `data_augmentation(img, n_rotate=3, blur=True)` | Returns up to three rotated copies (90°, 180°, 270°; default 3) and, optionally, a Gaussian-blurred copy. |
+| `cell_geometry(img)` | Makes both sides even, then pads the shorter side with black so the image becomes a centred square. |
+| `cell_transform(img, key)` | Converts an image to a `float32` tensor. `key=0` adds ImageNet normalisation, `key=1` only scales to [0, 1]. |
+
+### `Basic_Utils.py` — data, annotations, inference and SAHI
+
+The main working module. It finds files, checks datasets, reads ground truth,
+runs models and handles SAHI tiling.
+
+| Function | What it does |
+|---|---|
+| `IMAGE_EXTENSIONS` | Tuple of file extensions treated as images (case-insensitive). |
+| `img_loc(path)` | Recursively lists image, `.json` and `.txt` files under a folder. Returns `(img_list, json_list, txt_list)`. |
+| `ai_analytics(file, image_path, model, name='RFDETR', key=True, mode='Detection')` | Runs RF-DETR / YOLO detection or CNN classification on one image (the model is moved to the GPU if available). For detection it also reads the COCO ground truth and can draw predictions (blue) and ground truth (green). |
+| `dataset_check(file)` | Checks that the images in a folder and the COCO json agree. Returns five counts (images, json images, annotated images, categories, used categories). |
+| `provide_annotations(json_path, file_name, key='COCO')` | Returns the ground-truth boxes and labels for one image, from a COCO json or from the `'Vanila'` multi-json format. |
+| `SAHI_generation(image_path, ...)` | Slices a large image into tiles and saves them (the output folder is deleted first if it exists). |
+| `SAHI_analysis(image_path, model_det, model_clss=None, ...)` | Detects (and optionally classifies) objects on every tile and draws them on the full image. |
+
+### `AI_Metrics.py` — detection metrics
+
+Scores a detector on a single image against COCO ground truth. Boxes are in
+`(x_min, y_min, x_max, y_max)` format.
+
+| Function | What it does |
+|---|---|
+| `IOU_calc(target_pts, gt_pts)` | IoU of one box against a list of ground-truth boxes. |
+| `mAP_calc(bboxes, gt_bboxes)` | Running precision and recall for IoU thresholds 0.50 – 0.90. |
+| `AUC_calc(precision, recall)` | Builds the smoothed precision curve used for the area under the curve. |
+| `detection_metrics(json_file, img_file, model_test)` | End-to-end evaluation. Returns `(mAP_50, mAP_50_95)`. |
+
+---
+
+## Requirements
+
+* Python 3.9+
+* `numpy`
+* `opencv-python`
+* `torch`
+* `torchvision` (0.16 or newer, for `torchvision.transforms.v2.ToImage`)
+* `matplotlib` (imported by the modules)
+* `sahi`
+* A detector with a `.predict()` method (RF-DETR or Ultralytics YOLO) if you
+  use `ai_analytics`, `SAHI_analysis` or `detection_metrics`.
+
+## Quick example
+
+```python
+from Computer_vision_assisting_tools.Basic_Utils import img_loc, dataset_check
+from Computer_vision_assisting_tools.Image_Utils import image_processing
+
+images, jsons, txts = img_loc("my_dataset")      # find all files
+print(dataset_check("my_dataset"))               # sanity-check images vs json
+
+import cv2
+img = cv2.imread(images[0])
+img_clahe = image_processing(img, normalisation="Clahe")
+```
+
+## Documentation style
+
+Every module, function and inner helper has a NumPy-style docstring
+(`Parameters`, `Returns`, `Examples`). Use `help(function_name)` to read
+them.
+
+## Author
+
+Created and maintained by **Shounak Sanyal**.

computer_vision_assistant_package-1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "Computer_Vision_Assistant_Package"
+version = "1.0"
+authors = [
+  { name="Shounak Sanyal", email="shounaksanyal1902@outlook.com" },
+]
+description = "A user friendly package assiting in the most common computer vision tasks"
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "Programming Language :: Python :: 3",
+]
+license = "MIT"
+license-files = ["License.txt"]
+
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/Computer_Vision_Assistant_Package"]

computer_vision_assistant_package-1.0/src/Computer_Vision_Assistant_Package/AI_Metrics.py

@@ -0,0 +1,241 @@
+"""Detection metrics for object detectors.
+
+Functions to score how well a detector's boxes match the ground-truth boxes:
+IoU, precision / recall and mAP. All boxes are in
+``(x_min, y_min, x_max, y_max)`` pixel format.
+
+The overall flow is::
+
+    detection_metrics
+        |-- provide_annotations()  (Basic_Utils)  -> ground-truth boxes
+        |-- ai_analytics()         (Basic_Utils)  -> predicted boxes
+        |-- IOU_calc()             -> IoU of each prediction vs the GT boxes
+        |-- mAP_calc()             -> precision / recall at each IoU threshold
+        `-- AUC_calc()             -> smoothed precision curve for the area
+
+Functions
+---------
+IOU_calc
+    Intersection-over-Union of one box against a list of boxes.
+mAP_calc
+    Precision and recall lists for IoU thresholds 0.50 to 0.90.
+AUC_calc
+    Builds the (recall, smoothed precision) curve used to compute the area.
+detection_metrics
+    End-to-end mAP@0.5 and mAP@0.5:0.95 for one image.
+
+Author: Shounak Sanyal
+"""
+import os, json, cv2
+import numpy as np
+from .Basic_Utils import *
+
+
+def IOU_calc(target_pts, gt_pts):
+    """Compute the IoU of one predicted box against every ground-truth box.
+
+    IoU (Intersection over Union) tells how much two boxes overlap:
+    0 means no overlap and 1 means the boxes are identical.
+
+    Parameters
+    ----------
+    target_pts : sequence of 4 numbers
+        The predicted box as ``(x_min, y_min, x_max, y_max)``.
+    gt_pts : list of sequence of 4 numbers
+        Ground-truth boxes, each as ``(x_min, y_min, x_max, y_max)``.
+
+    Returns
+    -------
+    IOU_arr : list of float
+        One IoU value (0 to 1) per ground-truth box, in the same order as
+        ``gt_pts``.
+
+    Examples
+    --------
+    >>> IOU_calc((0, 0, 10, 10), [(5, 5, 15, 15), (0, 0, 10, 10)])
+    [0.14285714285714285, 1.0]
+    """
+    IOU_arr=[]
+    for i in range(0, len(gt_pts)):
+        x_gt0, y_gt0,x_gt1, y_gt1=gt_pts[i]
+        x_tgt0, y_tgt0, x_tgt1, y_tgt1= target_pts
+        w_gt, h_gt, w_tgt, h_tgt= x_gt1- x_gt0, y_gt1- y_gt0, x_tgt1- x_tgt0, y_tgt1- y_tgt0
+        x_edge, y_edge= min(x_gt1, x_tgt1), min(y_gt1, y_tgt1)
+        x_ref, y_ref= max(x_gt0, x_tgt0), max(y_gt0, y_tgt0)
+
+        if (x_ref>=x_edge) or (y_ref>= y_edge):
+            Intersection=0
+        else:
+            w,h= x_edge-x_ref, y_edge-y_ref
+            Intersection= h*w
+        Union= (h_gt*w_gt)+ (h_tgt*w_tgt)- Intersection
+        IOU= Intersection/Union
+
+        IOU_arr.append(IOU)
+
+    return IOU_arr
+
+def mAP_calc(bboxes, gt_bboxes):
+    """Compute running precision and recall for IoU thresholds 0.50 to 0.90.
+
+    The predictions must be sorted by confidence (highest first). For each IoU
+    threshold (0.50, 0.55, ..., 0.90) the predictions are visited in order. A
+    prediction counts as a true positive if its IoU reaches the threshold and its
+    matched ground-truth box has not been used yet; otherwise it is a false
+    positive. Precision and recall are recorded after every prediction.
+
+    Parameters
+    ----------
+    bboxes : array-like of float
+        The IoU value of each prediction, sorted by descending confidence.
+    gt_bboxes : array-like of int
+        For each prediction, the index of the ground-truth box it overlaps
+        most (same length and order as ``bboxes``).
+
+    Returns
+    -------
+    net_precision_arr : list of list of float
+        One list per threshold; each holds the precision after every
+        prediction.
+    net_recall_arr : list of list of float
+        Same layout as ``net_precision_arr``, but for recall.
+    """
+    thresh_limits= np.arange(0.5, 1, 0.05)
+    net_precision_arr, net_recall_arr=[],[]
+    for index in range(0, len(thresh_limits)):
+        net_positive= len(np.unique(gt_bboxes))
+        true_positive, false_positive=0,0
+        precision_arr, recall_arr=[],[]
+        checked_gt=[]
+        for i in range(0, len(bboxes)):
+            if bboxes[i]< thresh_limits[index]:
+                
+                false_positive+=1
+            else:
+                if gt_bboxes[i] not in checked_gt:
+                    true_positive+=1
+                    checked_gt.append(gt_bboxes[i])
+                else:
+                    false_positive+=1
+                
+            precision= true_positive/(true_positive+false_positive)
+            recall= true_positive/net_positive
+            precision_arr.append(precision)
+            recall_arr.append(recall)
+        net_precision_arr.append(precision_arr)
+        net_recall_arr.append(recall_arr)
+
+    return net_precision_arr, net_recall_arr
+
+def AUC_calc(precision, recall):
+    """Build the smoothed precision-recall curve used to get the area.
+
+    Each precision value is replaced by the highest precision found at or after
+    that point, so the curve never goes up as recall increases. The recall values
+    are returned unchanged.
+
+    Parameters
+    ----------
+    precision : sequence of float
+        Precision values in prediction order (one list from ``mAP_calc``).
+    recall : sequence of float
+        Recall values in the same order.
+
+    Returns
+    -------
+    x_arr : sequence of float
+        The recall values.
+    y_arr : list of float
+        The smoothed precision values, same length as ``precision``.
+    """
+    x_arr, y_arr=[],[]
+    for i in range(0, len(precision)):
+        if precision[i]> np.max(precision[i:]):
+            y_arr.append(precision[i])
+        else:
+            y_arr.append(np.max(precision[i:]))
+    x_arr= recall
+
+    return x_arr, y_arr
+
+def detection_metrics(json_file, img_file, model_test):
+    """Evaluate a detector on one image and return mAP@0.5 and mAP@0.5:0.95.
+
+    Steps: load the ground truth from a COCO json, run the model, match every
+    prediction to its best-overlapping ground-truth box, sort by confidence,
+    compute precision / recall for each IoU threshold and integrate the area.
+
+    Parameters
+    ----------
+    json_file : str
+        Path to the COCO-format annotation file that lists ``img_file``.
+    img_file : str
+        Path to the image to evaluate.
+    model_test : object
+        Loaded detection model (RF-DETR style) with a ``.predict(image_path)``
+        method that returns boxes, labels and confidence scores.
+
+    Returns
+    -------
+    mAP_50 : float
+        Score at IoU threshold 0.50, rounded to 3 decimals.
+    mAP_50_95 : float
+        Score averaged over the IoU thresholds, rounded to 3 decimals.
+
+    Examples
+    --------
+    >>> mAP_50, mAP_50_95 = detection_metrics("annotations.json", "img_01.png", model)
+    """
+    gt_pts, gt_indices=[],[]
+    gt_coords, gt_labels=provide_annotations(json_file, img_file)
+
+    for j in range(0, len(gt_coords)):
+        x0, y0 = int(gt_coords[j][0]), int(gt_coords[j][1])
+        x1, y1 = int(gt_coords[j][2])+ x0, int(gt_coords[j][3])+ y0
+        gt_pts.append((x0,y0, x1,y1))
+        gt_indices.append(j)
+
+    IOU_arr=[]
+    IOU_checkpoints_gt=[]
+
+    _, coords, labels, _,confidence= ai_analytics(None, img_file, model_test)
+    for j in range(0, len(coords)):
+        x0, y0 = int(coords[j][0]), int(coords[j][1])
+        x1, y1 = int(coords[j][2]), int(coords[j][3])
+        tgt_pt=(x0,y0 ,x1,y1)
+        IOU=IOU_calc(tgt_pt, gt_pts)
+        IOU_checkpoints_gt.append(gt_indices[np.argmax(IOU)])
+        IOU=round(np.max(IOU),2)
+        IOU_arr.append(IOU)
+    
+    confidence_arr= np.array(confidence)
+    IOU_arr= np.array(IOU_arr)
+    IOU_checkpoints_gt= np.array(IOU_checkpoints_gt)
+    index= np.argsort(confidence_arr)[::-1]
+    IOU_arr= IOU_arr[index]
+    IOU_checkpoints_gt= IOU_checkpoints_gt[index]
+
+    net_precision, net_recall= mAP_calc(IOU_arr, IOU_checkpoints_gt)
+    net_area=0
+    for j in range(0, len(net_precision)):
+        x,y= AUC_calc(net_precision[j], net_recall[j])
+
+        area_arr=[]
+        area_i=0
+        for k in range(0, len(x)):
+            if k<len(x)-1:
+                w= x[k+1]-x[k]
+            else:
+                w=0
+            h= y[k]
+            area=(h*w)+ area_i
+            area_arr.append(area)
+            area_i= area_arr[-1]
+        net_area+=area_i
+        if j==0:
+            mAP_50= area_i
+    mAP_50_95= net_area/10
+    mAP_50, mAP_50_95= round(mAP_50,3), round(mAP_50_95,3)
+
+    print('net mAP_50', mAP_50, 'net mAP_50:95', mAP_50_95)
+    return mAP_50, mAP_50_95