locals-api 0.1.0__tar.gz

locals_api-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: locals-api
+Version: 0.1.0
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Requires-Dist: matplotlib

locals_api-0.1.0/README.md

@@ -0,0 +1,28 @@
+# LOCALS
+
+Rapid experimentation framework for the LOCALS detector.
+
+## Installation
+
+Install PyTorch according to your CUDA version.
+
+Then:
+
+```bash
+pip install locals-api
+```
+
+## Example
+
+```python
+from locals import run
+
+run(
+    seed=1111,
+    train_split=0.8,
+    test_split=0.1,
+    images_dir="dataset/images",
+    labels_dir="dataset/labels",
+    num_epochs=50,
+)
+```

locals_api-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "locals-api"
+version = "0.1.0"
+requires-python = ">=3.10"
+
+dependencies = [
+    "numpy",
+    "opencv-python",
+    "matplotlib",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

locals_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

locals_api-0.1.0/src/locals/__init__.py

@@ -0,0 +1,6 @@
+from .locals import LOCALS
+from .dataset import LOCALSDataset
+from .figmaker import visualise_dataset, visualise_predictions
+from .runner import run
+
+__all__ = ['LOCALS', 'LOCALSDataset', 'visualise_dataset', 'visualise_predictions', 'run']

locals_api-0.1.0/src/locals/architectures.py

@@ -0,0 +1,65 @@
+import torch
+import torch.nn as nn
+
+from .blocks import ResnetBlock, ConvBlock
+
+class LOCALSn(nn.Module):
+    def __init__(self):
+        super().__init__()
+        
+        self.model = nn.Sequential(
+            ConvBlock(input_channels=3, output_channels=16, kernel_size=2, stride=2), # 224
+            ResnetBlock(input_channels=16, output_channels=32), # 112
+            ResnetBlock(input_channels=32, output_channels=64), # 56
+            ConvBlock(input_channels=64, output_channels=128, kernel_size=2, stride=2), # 28
+            ResnetBlock(input_channels=128, output_channels=256), # 14
+            ResnetBlock(input_channels=256, output_channels=256), # 7
+        )
+        
+        # 1x1 conv is important here because we do not want to do feature extraction in heads
+        
+        self.head = nn.Sequential(
+            ConvBlock(input_channels=256, output_channels=3, activation=False),
+        )
+        
+    def forward(self, x):
+        out = self.model(x)
+        out = self.head(out)
+        out = out.permute(0, 2, 3, 1) # [B, 7, 7, 3]
+        out = torch.sigmoid(out)
+        return out
+    
+class LOCALSs(nn.Module):
+    def __init__(self):
+        super().__init__()
+        
+        self.model = nn.Sequential(
+            ConvBlock(input_channels=3, output_channels=16, kernel_size=3, padding=1), # 448
+            ResnetBlock(input_channels=16, output_channels=32), # 224
+            ResnetBlock(input_channels=32, output_channels=64), # 112
+            ResnetBlock(input_channels=64, output_channels=128), # 56
+            ResnetBlock(input_channels=128, output_channels=256), # 28
+            ResnetBlock(input_channels=256, output_channels=512), # 14
+            ResnetBlock(input_channels=512, output_channels=256), # 7
+        )
+        
+        # 1x1 conv is important here because we do not want to do feature extraction in heads
+        
+        self.loc_head = nn.Sequential(
+            ConvBlock(input_channels=256, output_channels=64),
+            ConvBlock(input_channels=64, output_channels=16),
+            ConvBlock(input_channels=16, output_channels=2, activation=False),
+        )
+        
+        self.class_head = nn.Sequential(
+            ConvBlock(input_channels=256, output_channels=1, activation=False),
+        )
+        
+    def forward(self, x):
+        out =  self.model(x)
+        loc_info = self.loc_head(out) # [B, 2, 7, 7]
+        class_info = self.class_head(out) # [B, 1, 7, 7]
+        out = torch.concatenate([loc_info, class_info], dim=1) # [B, 3, 7, 7]
+        out = out.permute(0, 2, 3, 1) # [B, 7, 7, 3]
+        out = torch.sigmoid(out)
+        return out

locals_api-0.1.0/src/locals/blocks.py

@@ -0,0 +1,56 @@
+import torch.nn as nn
+
+'''
+This block models the skip connection introduced in the Resnet paper 2015.
+'''
+
+class ResnetBlock(nn.Module):
+    def __init__(self, input_channels, output_channels):
+        super().__init__()
+        
+        self.conv1 = nn.Conv2d(in_channels=input_channels, out_channels=output_channels, kernel_size=3, padding=1)
+        self.conv2 = nn.Conv2d(in_channels=output_channels, out_channels=output_channels, kernel_size=3, stride=2, padding=1)
+        self.downsamp_conv = nn.Conv2d(in_channels=input_channels, out_channels=output_channels, kernel_size=2, stride=2)
+        self.relu = nn.ReLU()
+        
+        self.bn1 = nn.BatchNorm2d(output_channels)
+        self.bn2 = nn.BatchNorm2d(output_channels)
+        self.downsamp_bn = nn.BatchNorm2d(output_channels)
+        
+    def forward(self, x):
+        # feature extraction
+        out = self.conv1(x)
+        out = self.bn1(out)
+        out = self.relu(out)
+        
+        # reduce H and W by 2
+        out = self.conv2(out)
+        out = self.bn2(out)
+        
+        # bring x to required number of channels
+        downsamp_x = self.downsamp_conv(x)
+        downsamp_x = self.downsamp_bn(downsamp_x)
+        
+        # skip connection
+        return self.relu(out + downsamp_x)
+    
+'''
+Simple 1x1 convolution block, nothing much to see here.
+'''
+
+class ConvBlock(nn.Module):
+    def __init__(self, input_channels, output_channels, kernel_size=1, padding=0, stride=1, activation=True):
+        super().__init__()
+        
+        self.channel_downsamp_conv = nn.Conv2d(in_channels=input_channels, out_channels=output_channels, kernel_size=kernel_size, padding=padding, stride=stride)
+        self.channel_downsamp_bn = nn.BatchNorm2d(output_channels)
+        self.relu = nn.ReLU()
+        self.activation = activation
+        
+    def forward(self, x):
+        out = self.channel_downsamp_conv(x)
+        out = self.channel_downsamp_bn(out)
+        if self.activation:
+            out = self.relu(out)
+        
+        return out

locals_api-0.1.0/src/locals/constants.py

@@ -0,0 +1 @@
+NUM_GRID_CELLS = 7

locals_api-0.1.0/src/locals/dataset.py

@@ -0,0 +1,78 @@
+import cv2
+import torch
+import numpy as np
+from torch.utils.data import DataLoader, Dataset, random_split
+
+import os
+
+class LOCALSDataset(Dataset):
+    def __init__(self, images_dir, labels_dir):
+        self.image_list = [
+            f_name for f_name in os.listdir(images_dir)
+            if f_name.lower().endswith((".png", ".jpg", ".jpeg"))
+        ]
+        self.images_dir = images_dir
+        self.labels_dir = labels_dir
+        self.image_size=448
+
+    def __len__(self):
+        return len(self.image_list)
+
+    def __getitem__(self, idx):
+        image_name = self.image_list[idx]
+
+        image = cv2.imread(
+            os.path.join(self.images_dir,
+                         image_name)
+        )
+        image = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+        image = cv2.resize(image, (self.image_size, self.image_size))
+        image = image.astype(np.float32) / 255.0
+        image = torch.from_numpy(image).permute(2, 0, 1)
+
+        prefix = image_name.split('.')[0]
+        annotation_matrix = np.load(os.path.join(self.labels_dir, f'{prefix}.npy'))
+
+        return image, annotation_matrix
+    
+    def get_dataloaders(self, train_split = 0.8, test_split = 0.1, batch_size=16):
+        assert (
+            0 < train_split < 1
+            and 0 < test_split < 1
+            and train_split + test_split <= 1
+        ), "train_split + test_split must not exceed 1."
+        
+        N = len(self)
+        train_size = int(train_split * N)
+        test_size = int(N * test_split)
+        val_size = N - (train_size + test_size)
+        
+        train_dataset, test_dataset, val_dataset = random_split(
+            self,
+            [train_size, test_size, val_size]
+        )
+        
+        train_loader = DataLoader(
+            train_dataset,
+            batch_size=batch_size,
+            shuffle=True,
+            pin_memory=True
+        )
+
+        test_loader = DataLoader(
+            test_dataset,
+            batch_size=1,
+            shuffle=True,
+            pin_memory=True
+        )
+
+        val_loader = DataLoader(
+            val_dataset,
+            batch_size=batch_size,
+            shuffle=False,
+            pin_memory=True
+        ) if val_size > 0 else None
+        
+        if val_size > 0:
+            return train_loader, test_loader, val_loader
+        return train_loader, test_loader

locals_api-0.1.0/src/locals/evaluator.py

@@ -0,0 +1,192 @@
+import torch
+import numpy as np
+from torch.utils.data import DataLoader
+
+from .math import pearson_corr
+from .constants import NUM_GRID_CELLS
+
+def find_recall_precision_f1_score(model, data, threshold=0.5, num_batches=100):
+    if not isinstance(data, DataLoader):
+        data = DataLoader(
+            data,
+            batch_size=1,
+            shuffle=False
+        )
+    model.eval()
+    
+    true_positives = 0
+    false_positives = 0
+    false_negatives = 0
+    
+    with torch.no_grad():
+        for batch_idx, (images, labels) in enumerate(data):
+            if batch_idx >= num_batches:
+                break
+            
+            images_tensor = images.to(model.device)
+            predictions_batch = model(images_tensor) # [B, 7, 7, 3]
+            batch_size = images_tensor.shape[0]
+            
+            for i in range(batch_size):
+                prediction = predictions_batch[i]
+                prediction = prediction.cpu().numpy()
+                
+                label = labels[i]
+                label_numpy = label.cpu().numpy()
+                
+                # compare predictions vs labels
+                for j in range(7):
+                    for k in range(7):
+                        pred_obj = prediction[j, k, -1]
+                        label_obj = label_numpy[j, k, -1]
+                        
+                        if pred_obj > threshold and label_obj > 0:
+                            true_positives += 1
+                        elif pred_obj > threshold and label_obj == 0:
+                            false_positives += 1
+                        elif pred_obj <= threshold and label_obj > 0:
+                            false_negatives += 1
+    
+    recall = true_positives / (true_positives + false_negatives) if (true_positives + false_negatives) > 0 else 0
+    precision = true_positives / (true_positives + false_positives) if (true_positives + false_positives) > 0 else 0
+    f1_score = 2 * (precision * recall) / (precision + recall) if (precision + recall) > 0 else 0
+    
+    return recall, precision, f1_score
+
+def find_mAP(model, data, class_threshold=0.5):
+    if not isinstance(data, DataLoader):
+        data = DataLoader(
+            data,
+            batch_size=1,
+            shuffle=False
+        )
+    model.eval()
+    
+    dist_thresholds = [0.5, 0.55, 0.6, 0.65, 0.7, 0.75, 0.8, 0.85, 0.9, 0.95]
+    APs = []
+    
+    for dist_threshold in dist_thresholds:
+        all_detections = []
+        num_trues = 0
+        for batched_images, batched_labels in data:
+            batched_images = batched_images.to(model.device)
+            batched_predictions = model(batched_images).detach().cpu()
+            batch_size = batched_images.shape[0]
+            
+            for b in range(batch_size):
+                predictions = batched_predictions[b]
+                labels = batched_labels[b]
+                
+                predictions = predictions.reshape(-1, predictions.shape[-1])
+                trues = labels.reshape(-1, labels.shape[-1])
+                taken_trues = [False] * trues.shape[0]
+
+                num_trues += torch.sum(trues[:, 2] == 1).item()
+                indices = torch.arange(predictions.shape[0])
+                order = predictions[:, -1].argsort(descending=True)
+                predictions = predictions[order]
+                indices = indices[order]
+                
+                for i in range(predictions.shape[0]):
+                    pred_xnb, pred_ynb, pred_conf = predictions[i]
+                    cell_idx = indices[i]
+                    row = cell_idx // NUM_GRID_CELLS
+                    col = cell_idx % NUM_GRID_CELLS
+                    pred_x = ((col / NUM_GRID_CELLS) + (pred_xnb * (1 / NUM_GRID_CELLS)))
+                    pred_y = ((row / NUM_GRID_CELLS) + (pred_ynb * (1 / NUM_GRID_CELLS)))
+                    
+                    if pred_conf >= class_threshold:
+                        closest_idx = -1
+                        closest_distance = torch.inf
+                        for j in range(trues.shape[0]):
+                            true_xnb, true_ynb, true_conf = trues[j]
+                            row = j // NUM_GRID_CELLS
+                            col = j % NUM_GRID_CELLS
+                            true_x = ((col / NUM_GRID_CELLS) + (true_xnb * (1 / NUM_GRID_CELLS)))
+                            true_y = ((row / NUM_GRID_CELLS) + (true_ynb * (1 / NUM_GRID_CELLS)))
+                            
+                            if true_conf >= 0.5:
+                                pred_coord = torch.tensor([pred_x, pred_y])
+                                true_coord = torch.tensor([true_x, true_y])
+                
+                                dist = torch.sqrt(torch.sum((pred_coord - true_coord) ** 2, dim=-1))
+                                if dist < closest_distance:
+                                    closest_distance = dist
+                                    closest_idx = j
+                        
+                        dist_conf = 1 - torch.sigmoid(69 * (closest_distance - 0.1))
+                        if closest_idx != -1 and not taken_trues[closest_idx] and dist_conf >= dist_threshold:
+                            taken_trues[closest_idx] = True
+                            all_detections.append((pred_conf.item(), 1, 0))
+                        else:
+                            all_detections.append((pred_conf.item(), 0, 1))
+    
+        all_detections.sort(key=lambda x: x[0], reverse=True)
+        TP = [d[1] for d in all_detections]
+        FP = [d[2] for d in all_detections]
+        
+        TP_cum = np.cumsum(TP)
+        FP_cum = np.cumsum(FP)
+
+        precisions = TP_cum / (TP_cum + FP_cum + 1e-6)
+        recalls = TP_cum / (num_trues + 1e-6)
+        AP = np.trapezoid(precisions, recalls)
+        APs.append(AP)
+    
+    return sum(APs)/len(APs)
+
+def find_mCS(model, data, threshold=0.5, num_batches=100):
+    if not isinstance(data, DataLoader):
+        data = DataLoader(
+            data,
+            batch_size=1,
+            shuffle=False
+        )
+    model.eval()
+    
+    correlations = []
+
+    with torch.no_grad():
+        for batch_idx, (images, labels) in enumerate(data):
+            if batch_idx >= num_batches:
+                break
+
+            images_tensor = images.to(model.device)
+
+            predictions_batch = model(images_tensor)
+            batch_size = images_tensor.shape[0]
+
+            for i in range(batch_size):
+                prediction = predictions_batch[i]
+                prediction = prediction.cpu().numpy()
+
+                label = labels[i]
+
+                # extract predicted points
+                predicted_points = []
+                for row in range(prediction.shape[0]):
+                    for col in range(prediction.shape[1]):
+                        cell = prediction[row][col]
+                        if cell[-1] > threshold:
+                            xnb, ynb, c = cell
+                            xn = ((col / NUM_GRID_CELLS) + (xnb * (1 / NUM_GRID_CELLS)))
+                            yn = ((row / NUM_GRID_CELLS) + (ynb * (1 / NUM_GRID_CELLS)))
+                            predicted_points.append([xn, yn])
+
+                # extract label points
+                label_points = []
+                for row in range(label.shape[0]):
+                    for col in range(label.shape[1]):
+                        cell = label[row][col]
+                        if cell[-1] > 0:
+                            xnb, ynb, c = cell
+                            xn = ((col / NUM_GRID_CELLS) + (xnb * (1 / NUM_GRID_CELLS)))
+                            yn = ((row / NUM_GRID_CELLS) + (ynb * (1 / NUM_GRID_CELLS)))
+                            label_points.append([xn, yn])
+
+                if not predicted_points:
+                    correlations.append(0)
+                else:
+                    correlations.append(abs(pearson_corr(label_points + predicted_points)))
+
+    return np.mean(correlations) if correlations else 0.0

locals_api-0.1.0/src/locals/figmaker.py

@@ -0,0 +1,212 @@
+import torch
+import matplotlib.pyplot as plt
+from torch.utils.data import DataLoader
+
+import os
+
+from .constants import NUM_GRID_CELLS
+from .math import smooth_curve, closest_factors
+
+image_size = 448
+
+def save_loss_fig(train_loss_ot: list, val_loss_ot: list):
+    os.makedirs('figures', exist_ok=True)
+    
+    # smooth the losses
+    smooth_train_loss = smooth_curve(train_loss_ot)
+    smooth_val_loss = smooth_curve(val_loss_ot) if val_loss_ot else None
+
+    # plot the smoothed losses
+    epochs = range(1, len(train_loss_ot) + 1)
+    plt.figure(figsize=(10, 6), dpi=300)
+    plt.plot(epochs, smooth_train_loss, color='blue', linewidth=2)
+    if val_loss_ot:
+        plt.plot(epochs, smooth_val_loss, color='red', linewidth=2)
+    plt.title(r'Smoothed Training Loss Over Epochs', fontsize=14)
+    plt.xlabel(r'Epoch', fontsize=12)
+    plt.ylabel(r'Loss', fontsize=12)
+    plt.grid(True, which='both', linestyle='--', linewidth=0.5, alpha=0.7)
+    plt.xticks(fontsize=10)
+    plt.yticks(fontsize=10)
+    plt.tight_layout()
+    plt.savefig("figures/smoothed_training_loss.png", dpi=300)
+    
+def visualise_dataset(data, num_images, plot_title=None):
+    if not isinstance(data, DataLoader):
+        data = DataLoader(
+            data,
+            batch_size=1,
+            shuffle=False
+        )
+    
+    rows, cols = closest_factors(num_images)
+    fig, axes = plt.subplots(rows, cols, figsize=(3 * cols, max(3 * rows, 4)), squeeze=False)
+    fig.suptitle('Visualising Dataset of LOCALS for Pencils') if not plot_title else fig.suptitle(plot_title)
+    image_idx = 0
+    axes = axes.flatten()
+    
+    for images, labels in data:
+        if image_idx >= num_images: break
+        for i, image in enumerate(images):
+            if image_idx >= num_images: break
+            image_plt = image.permute(1, 2, 0)
+            ax = axes[image_idx]
+            
+            ax.axis('off')
+            label = labels[i]
+            ax.set_title(f'Sample {image_idx + 1}')
+            ax.imshow(image_plt)
+            
+            grid_size = image_size / NUM_GRID_CELLS
+            for g in range(NUM_GRID_CELLS + 1):
+                pos = g * grid_size
+                
+                # vertical lines
+                ax.axvline(
+                    x=pos,
+                    color='white',
+                    linewidth=0.5,
+                    alpha=0.5
+                )
+
+                # horizontal lines
+                ax.axhline(
+                    y=pos,
+                    color='white',
+                    linewidth=0.5,
+                    alpha=0.5
+                )
+            
+            for j in range(NUM_GRID_CELLS):
+                for k in range(NUM_GRID_CELLS):
+                    xnb, ynb, c = label[j][k]
+                    if c < 0.5:
+                        continue
+                    x = ((k / NUM_GRID_CELLS) + (xnb * (1 / NUM_GRID_CELLS))) * image_size
+                    y = ((j / NUM_GRID_CELLS) + (ynb * (1 / NUM_GRID_CELLS))) * image_size
+                    
+                    ax.scatter(x, y, color='red', marker='x', s=40)
+            image_idx += 1
+    
+    plt.savefig('figures/visualised_dataset.png', dpi=300, bbox_inches='tight') if not plot_title else \
+        plt.savefig(f"figures/visualised_dataset_{plot_title.lower().replace(' ', '_')}.png", dpi=300, bbox_inches='tight')
+    plt.show()
+    
+def visualise_predictions(model, data, num_images, plot_title=None):
+    if not isinstance(data, DataLoader):
+        data = DataLoader(
+            data,
+            batch_size=1,
+            shuffle=False
+        )
+    model.eval()
+
+    with torch.no_grad():
+        rows, cols = closest_factors(num_images)
+        fig, axes = plt.subplots(
+        rows,
+        cols,
+        figsize=(3 * cols, 3 * rows + 1),
+        squeeze=False
+    )
+        fig.suptitle('Visualising Predictions of LOCALS for Pencils') if not plot_title else fig.suptitle(plot_title)
+        axes = axes.flatten()
+        image_idx = 0
+        
+        for images, labels in data:
+            if image_idx >= num_images: break
+            outputs = model(images.to(model.device))
+            for i, image in enumerate(images):
+                image_plt = image.permute(1, 2, 0)
+                label = labels[i]
+                output = outputs[i].detach().cpu()
+                ax = axes[image_idx]
+                ax.axis('off')
+                ax.imshow(image_plt.detach().cpu())
+                ax.set_title(f'Prediction {image_idx + 1}')
+                grid_size = image_size / NUM_GRID_CELLS
+                
+                for g in range(NUM_GRID_CELLS + 1):
+                    pos = g * grid_size
+                    
+                    # vertical lines
+                    ax.axvline(
+                        x=pos,
+                        color='white',
+                        linewidth=0.5,
+                        alpha=0.5
+                    )
+
+                    # horizontal lines
+                    ax.axhline(
+                        y=pos,
+                        color='white',
+                        linewidth=0.5,
+                        alpha=0.5
+                    )
+
+                for j in range(NUM_GRID_CELLS):
+                    for k in range(NUM_GRID_CELLS):
+                        
+                        # ground truth
+                        xnb, ynb, c = label[j][k]
+
+                        if c.item() > 0.5:
+
+                            x = ((k / NUM_GRID_CELLS) + (xnb * (1 / NUM_GRID_CELLS))) * image_size
+                            y = ((j / NUM_GRID_CELLS) + (ynb * (1 / NUM_GRID_CELLS))) * image_size
+                            ax.scatter(
+                                x.detach().cpu(),
+                                y.detach().cpu(),
+                                color='yellow',
+                                marker='x',
+                                s=40,
+                                alpha=1
+                            )
+
+                        # prediction
+                        pxnb, pynb, pc = output[j][k]
+
+                        if pc.item() >= 0.5:
+
+                            x = ((k / NUM_GRID_CELLS) + (pxnb * (1 / NUM_GRID_CELLS))) * image_size
+                            y = ((j / NUM_GRID_CELLS) + (pynb * (1 / NUM_GRID_CELLS))) * image_size
+
+                            ax.scatter(
+                                x.detach().cpu(),
+                                y.detach().cpu(),
+                                color='red',
+                                marker='x',
+                                s=40,
+                                alpha=0.5,
+                            )
+                            
+                            ax.text(
+                                x.detach().cpu() + 5, # x offset
+                                y.detach().cpu() + 5, # y offset
+                                f'{pc.detach().cpu():.2f}',
+                                color='white',
+                                fontsize=10
+                            )
+                
+                image_idx += 1
+                
+        
+        fig.tight_layout(rect=[0, 0, 1, 0.95])
+        plt.savefig(f"figures/visualised_predictions_{plot_title.lower().replace(' ', '_')}.png", dpi=300, bbox_inches='tight') if plot_title else \
+            plt.savefig(f'figures/visualised_predictions.png')
+        plt.show()
+        
+def save_recall_precision_f1_score(recall, precision, f1_score):
+    metrics = ['Recall', 'Precision', 'F1 Score']
+    values = [recall, precision, f1_score]
+
+    plt.figure(figsize=(6, 4))
+    plt.bar(metrics, values, color=['skyblue', 'lightgreen', 'salmon'])
+    plt.ylim(0, 1.1)
+    plt.title('Model Classification Performance Metrics')
+    plt.ylabel('Score')
+    for i, v in enumerate(values):
+        plt.text(i, v + 0.02, f"{v:.2f}", ha='center')
+    plt.tight_layout()
+    plt.savefig("figures/recall-precision-f1score.png", dpi=300)

locals_api-0.1.0/src/locals/locals.py

@@ -0,0 +1,50 @@
+import torch
+from torch.utils.data import DataLoader
+
+from .trainer import train
+from .architectures import LOCALSn, LOCALSs
+from .figmaker import save_loss_fig, save_recall_precision_f1_score
+from .evaluator import find_recall_precision_f1_score, find_mAP, find_mCS
+
+class LOCALS:
+    def __init__(self, architecture='n', file_path=None, device='cuda'):
+        self.architecture = architecture
+        self.device = device
+        if architecture == 'n':
+            self.model = LOCALSn()
+            self.model.to(device)
+        if file_path:
+            self.model.load_state_dict(torch.load(file_path, weights_only=True))
+            
+    def __call__(self, images):
+        return self.model(images)
+            
+    def fit(self, train_loader: DataLoader, *, num_epochs=50, val_loader=None, epoch_to_lr={}, do_save_loss_fig=True):
+        train_loss_ot, val_loss_ot = train(train_loader, num_epochs, val_loader, self.model, self.device, epoch_to_lr)
+        self.model.load_state_dict(torch.load("best.pth", weights_only=True))
+        
+        if do_save_loss_fig:
+            save_loss_fig(train_loss_ot, val_loss_ot)
+            
+    def eval(self):
+        self.model.eval()
+    
+    def train(self):
+        self.model.train()
+        
+    def evaluate(self, data, do_save_fig=True):
+        recall, precision, f1_score = find_recall_precision_f1_score(self, data)
+        mAP = find_mAP(self, data)
+        mCS = find_mCS(self, data)
+            
+        if do_save_fig:
+            save_recall_precision_f1_score(recall, precision, f1_score)
+            
+        return {'recall': recall, 'precision': precision, 'f1_score': f1_score, 'mAP': mAP, 'mCS': mCS}
+    
+    def get_num_params(self):
+        num_params = sum(
+            p.numel()
+            for p in self.model.parameters()
+        )
+        return num_params 

locals_api-0.1.0/src/locals/losses.py

@@ -0,0 +1,63 @@
+import torch
+
+def locals_loss(beta=1.0, gamma=5.0):  
+    '''
+    beta: weight for localization loss
+    gamma: weight for objectness loss
+    '''
+    
+    def binary_focal_loss(pred, target, alpha=0.25, gamma=2.0, eps=1e-8):
+        '''
+        pred: predicted probabilities (after sigmoid)
+        target: ground truth (0 or 1)
+        alpha: weighting factor for class imbalance
+        gamma: focusing parameter for hard examples
+        '''
+        pred = pred.clamp(eps, 1.0 - eps)  # avoid log(0)
+        pt = pred * target + (1 - pred) * (1 - target)
+        loss = - alpha * (1 - pt) ** gamma * (target * torch.log(pred + eps) + (1 - target) * torch.log(1 - pred + eps))
+        return loss.mean()
+
+    def focal_localization_loss(pred_coords, true_coords, mask, alpha=0.25, gamma=2.0, eps=1e-8):
+        d = torch.sqrt(torch.sum((pred_coords - true_coords) ** 2, dim=-1))
+        pt = 1 - torch.sigmoid(20 * (d - 0.1))
+        pt = pt.clamp(eps, 1.0 - eps)
+        loss = - alpha * (1 - pt) ** gamma * mask * torch.log(pt)
+        if mask.sum() == 0:
+            return 0
+        
+        return (loss).sum() / mask.sum()
+        
+    # actual loss function
+    def loss_func(predicted, true):
+        # goal is to sum each loss for each prediction in each batch
+        loc_loss = 0
+        obj_loss = 0
+        
+        # iterate through each image in the batch
+        for i in range(true.shape[0]):
+            ith_predicted = predicted[i]
+            ith_true = true[i]
+
+            obj_mask = ith_true[..., 2]
+            true_coordinates = ith_true[..., :2]
+
+            obj_pred = ith_predicted[..., 2]
+            pred_coordinates = ith_predicted[..., :2]
+
+            # find localization loss
+            loc_loss += focal_localization_loss(pred_coordinates, true_coordinates, obj_mask)
+            
+            # find objectness loss
+            ith_obj_loss = binary_focal_loss(obj_pred, obj_mask)
+            obj_loss += ith_obj_loss
+
+        # first find mean loss
+        loc_loss /= true.shape[0]
+        obj_loss /= true.shape[0]
+
+        # then find total loss
+        total_loss = beta * loc_loss + gamma * obj_loss
+        return total_loss
+
+    return loss_func

locals_api-0.1.0/src/locals/math.py

@@ -0,0 +1,29 @@
+import numpy as np
+
+import math
+
+def smooth_curve(points, factor=0.9):
+    # applies exponential smoothing to a curve
+    smoothed = []
+    for point in points:
+        if smoothed:
+            smoothed.append(smoothed[-1] * factor + point * (1 - factor))
+        else:
+            smoothed.append(point)
+    return smoothed
+
+def closest_factors(n):
+    d = math.isqrt(n)  # integer sqrt
+    while n % d != 0:
+        d -= 1
+    return d, n // d
+
+# function that calculates the pearson correlation coefficient given a list of points
+def pearson_corr(points):
+    points_array = np.array(points)
+
+    x = points_array[:, 0]
+    y = points_array[:, 1]
+
+    corr = np.corrcoef(x, y)[0, 1]
+    return corr

locals_api-0.1.0/src/locals/runner.py

@@ -0,0 +1,67 @@
+import torch
+import numpy as np
+from torch.utils.flop_counter import FlopCounterMode
+
+import os
+import json
+import uuid
+
+from .locals import LOCALS
+from .dataset import LOCALSDataset
+
+def save_run_metrics(run_details: dict):
+    os.makedirs('runs', exist_ok=True)
+    
+    run_id = str(uuid.uuid4())
+    
+    with open(f'runs/run_metrics_{run_id}.json', 'w') as run_metrics_file:
+        json.dump(run_details, run_metrics_file)
+
+def run(*, seed: int,
+        train_split: float,
+        test_split: float,
+        images_dir: str,
+        labels_dir: str,
+        architecture='n',
+        num_epochs=50,
+        epoch_to_lr={}):
+    
+    # NumPy
+    np.random.seed(seed)
+
+    # PyTorch
+    torch.manual_seed(seed)
+    if torch.cuda.is_available():
+        torch.cuda.manual_seed(seed)
+        torch.cuda.manual_seed_all(seed)  # for multi-GPU
+        
+        torch.backends.cudnn.deterministic = True
+        torch.backends.cudnn.benchmark = False
+    
+    dataset = LOCALSDataset(images_dir, labels_dir)
+    train_loader, test_loader, val_loader = dataset.get_dataloaders(train_split, test_split)
+    
+    model = LOCALS(architecture)
+    model.fit(train_loader, num_epochs=num_epochs, val_loader=val_loader, epoch_to_lr=epoch_to_lr)
+    
+    flop_counter = FlopCounterMode(display=False)
+    with flop_counter:
+        for images, labels in test_loader:
+            outputs = model(images.to(model.device))
+            break
+    total_flops = flop_counter.get_total_flops()
+    
+    metrics= model.evaluate(test_loader)
+    run_details = {'seed': seed,
+                   'train_split': train_split,
+                   'test_split': test_split,
+                   'recall': metrics['recall'],
+                   'precision': metrics['precision'],
+                   'f1_score': metrics['f1_score'],
+                   'mAP': metrics['mAP'],
+                   'mCS': metrics['mCS'],
+                   'num_params': model.get_num_params(),
+                   'total_flops': total_flops}
+    
+    save_run_metrics(run_details)
+    return run_details

locals_api-0.1.0/src/locals/trainer.py

@@ -0,0 +1,83 @@
+import torch
+from tqdm import tqdm
+from torch.optim import Adam
+from torch.utils.data import DataLoader
+
+from .losses import locals_loss
+
+def train(train_loader: DataLoader,
+          num_epochs: int,
+          val_loader: DataLoader,
+          model: torch.nn.Module,
+          device='cuda',
+          epoch_to_lr = {}):
+    
+    model.to(device)
+    torch.save(model.state_dict(), "best.pth")
+    
+    optimizer = Adam(model.parameters(), lr=1e-3)
+    criterion = locals_loss()
+    validate = val_loader is not None
+    
+    train_loss_ot = []
+    val_loss_ot = []
+    avg_train_loss = 0
+    avg_val_loss = 0
+    min_val_loss = float('inf')
+    
+    for epoch in range(1, num_epochs + 1):
+        if epoch in epoch_to_lr:
+            new_lr = epoch_to_lr[epoch]
+            for param_group in optimizer.param_groups:
+                param_group["lr"] = new_lr
+            if validate:
+                model.load_state_dict(torch.load("best.pth", weights_only=True))
+            
+        model.train()
+        total_loss = 0
+
+        pbar = tqdm(train_loader, desc=f"Epoch {epoch}/{num_epochs}")
+
+        for inputs, targets in pbar:
+            inputs = inputs.to(device)
+            targets = targets.to(device)
+
+            optimizer.zero_grad()
+            outputs = model(inputs)
+
+            loss = criterion(outputs, targets)
+            loss.backward()
+            optimizer.step()
+
+            total_loss += loss.item()
+            
+        avg_train_loss = total_loss / len(train_loader)
+        train_loss_ot.append(avg_train_loss)
+        print(f'Avg Training Loss = {avg_train_loss}')
+            
+        if validate:
+            model.eval()
+            with torch.no_grad():
+                total_val_loss = 0
+
+                for images, labels in val_loader:
+                    images = images.to(device)
+                    labels = labels.to(device)
+
+                    outputs = model(images)
+                    
+                    loss = criterion(outputs, labels)
+                    total_val_loss += loss.item()
+                    
+            avg_val_loss = total_val_loss / len(val_loader)
+            val_loss_ot.append(avg_val_loss)
+            if avg_val_loss < min_val_loss:
+                min_val_loss = avg_val_loss
+                torch.save(model.state_dict(), "best.pth")
+            
+            print(f'Val Loss = {avg_val_loss}')
+    
+    if not validate:
+        torch.save(model.state_dict(), "best.pth")
+        
+    return train_loss_ot, val_loss_ot

locals_api-0.1.0/src/locals_api.egg-info/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: locals-api
+Version: 0.1.0
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Requires-Dist: opencv-python
+Requires-Dist: matplotlib

locals_api-0.1.0/src/locals_api.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+README.md
+pyproject.toml
+src/locals/__init__.py
+src/locals/architectures.py
+src/locals/blocks.py
+src/locals/constants.py
+src/locals/dataset.py
+src/locals/evaluator.py
+src/locals/figmaker.py
+src/locals/locals.py
+src/locals/losses.py
+src/locals/math.py
+src/locals/runner.py
+src/locals/trainer.py
+src/locals_api.egg-info/PKG-INFO
+src/locals_api.egg-info/SOURCES.txt
+src/locals_api.egg-info/dependency_links.txt
+src/locals_api.egg-info/requires.txt
+src/locals_api.egg-info/top_level.txt

locals_api-0.1.0/src/locals_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

locals_api-0.1.0/src/locals_api.egg-info/requires.txt

@@ -0,0 +1,3 @@
+numpy
+opencv-python
+matplotlib

locals_api-0.1.0/src/locals_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+locals