lidar-camera-image-recognition 0.1.0__tar.gz

lidar_camera_image_recognition-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Quito
+
+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.

lidar_camera_image_recognition-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: lidar-camera-image-recognition
+Version: 0.1.0
+Summary: Reproducible CNN, VGG16, and AV safety-framework experiments
+Author: Benjamin Quito, Larbi Esmahi
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/benjaminquito/ImageRecognition
+Project-URL: Repository, https://github.com/benjaminquito/ImageRecognition
+Project-URL: Paper, https://doi.org/10.4236/ojsst.2023.133006
+Keywords: computer-vision,image-classification,lidar,autonomous-vehicles,reproducible-research
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tensorflow<2.17,>=2.16
+Requires-Dist: numpy<2,>=1.26
+Requires-Dist: matplotlib<3.9,>=3.8
+Requires-Dist: Pillow<11,>=10.3
+Dynamic: license-file
+
+# LiDAR and Camera Image Recognition
+
+Reproducible code companion for:
+
+> Quito, B. and Esmahi, L. (2023). “Compare and Contrast LiDAR and Non-LiDAR
+> Technology in an Autonomous Vehicle: Developing a Safety Framework.”
+> *Open Journal of Safety Science and Technology*, 13, 101–131.
+> [https://doi.org/10.4236/ojsst.2023.133006](https://doi.org/10.4236/ojsst.2023.133006)
+
+The project reconstructs the executable parts of the paper and separates them
+from the proposed (not yet completed) vehicle experiment.
+
+## What is reproduced
+
+| Paper component | Package command | Output |
+|---|---|---|
+| 28 × 28 CNN on MNIST | `image-recognition train-mnist` | Saved model, metrics, history, and accuracy/loss plots |
+| ImageNet VGG16 inference | `image-recognition predict-vgg16` | Top-k labels and probabilities for an input image |
+| LiDAR/camera safety framework | `image-recognition safety` | Blank 25-run protocol and aggregated weather results |
+
+The MNIST network follows the architecture in sections 3.6.1–3.6.4: two
+5 × 5 convolution layers (32 and 64 filters), max pooling, a 1,024-unit dense
+layer, and a 10-class output. It contains 3,274,634 trainable parameters when
+dropout is disabled, matching the paper.
+
+The VGG16 script follows sections 3.7–3.8: resize to 224 × 224, apply Keras'
+VGG16 preprocessing, use ImageNet weights, and decode the ten most likely
+classes.
+
+## Important interpretation
+
+The paper reports several different numbers:
+
+- **99.29%** is the reported MNIST evaluation accuracy after 25 epochs.
+- **94.63%** is the top prediction probability for one bee photograph using
+  pretrained VGG16. It is a confidence score for one sample, not a dataset
+  accuracy and not a comparison of LiDAR against camera data.
+- The LiDAR/camera weather tables are an experimental proposal. No completed
+  sensor dataset or table values are published in the paper.
+
+Accordingly, this repository does not claim to reproduce a measured 94.63%
+LiDAR-vs-camera result. Exact floating-point results can vary by platform,
+TensorFlow version, initialization, and the input image.
+
+## Setup
+
+The paper used Python 3.10.4 and TensorFlow. A clean Python 3.10 environment is
+recommended.
+
+```bash
+python3.10 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install .
+```
+
+For development, use an editable installation so source changes are immediately
+available:
+
+```bash
+python -m pip install --editable .
+```
+
+Verify the installed package and command:
+
+```bash
+python -c "import image_recognition; print(image_recognition.__version__)"
+image-recognition --help
+```
+
+## Run the MNIST experiment
+
+Full 25-epoch reproduction:
+
+```bash
+image-recognition train-mnist --epochs 25 --output-dir artifacts/mnist
+```
+
+Optional dropout enhancement described in section 3.6.5:
+
+```bash
+image-recognition train-mnist --epochs 25 --dropout 0.5 \
+  --output-dir artifacts/mnist-dropout
+```
+
+For a quick pipeline check:
+
+```bash
+image-recognition train-mnist --epochs 1 --train-limit 2048 --test-limit 512 \
+  --output-dir artifacts/smoke
+```
+
+Each run writes `model.keras`, `metrics.json`, `history.csv`,
+`training_curves.png`, and `model_summary.txt`.
+
+## Run VGG16 inference
+
+```bash
+image-recognition predict-vgg16 path/to/image.jpg --top 10 \
+  --output artifacts/vgg16-prediction.json
+```
+
+The ImageNet weights download automatically on first use. To revisit the bee
+example, supply a bee image whose reuse rights you have; the original image is
+not distributed with the article.
+
+## Use the safety-framework scaffold
+
+Create a protocol with 25 runs for each combination of driver mode,
+technology, and weather condition:
+
+```bash
+image-recognition safety init data/safety_runs.csv --runs 25
+```
+
+Fill the measurement columns in the CSV, then aggregate results:
+
+```bash
+image-recognition safety summarize data/safety_runs.csv \
+  --output artifacts/safety_summary.csv
+```
+
+The long-form protocol captures accuracy, confidence, latency, obstacle
+detection, stopping distance, and notes. These fields support the paper's
+proposed extensions while keeping missing measurements blank.
+
+The prose names six conditions: sunny (`S`), cloudy (`C`), daytime rain
+(`DR`), fog (`F`), nighttime rain (`NR`), and snow (`SW`). Tables 3–6 also
+contain an unexplained `R` column. The scaffold preserves `R` as `rain` so the
+published table layout can be represented without silently discarding it.
+
+## Tests
+
+The lightweight tests do not download datasets or TensorFlow weights:
+
+```bash
+python -m unittest -v
+python -m compileall -q src
+```
+
+GitHub Actions runs these packaging checks automatically on every push and pull
+request. The original root-level Python scripts remain available as
+backward-compatible wrappers.
+
+## Published reproduction
+
+The verified 25-epoch run reached 99.20% test accuracy. See [RESULTS.md](RESULTS.md)
+for the environment, comparison with the paper, raw metrics, and curves.
+
+## Reproducibility boundary
+
+This code reproduces the published software procedures as closely as the paper
+allows. A direct LiDAR-versus-camera safety comparison still requires paired,
+time-synchronized sensor captures, ground-truth labels, weather metadata, and
+the 25 physical runs per condition proposed in section 4. Those data are not
+included in the publication.

lidar_camera_image_recognition-0.1.0/README.md

@@ -0,0 +1,156 @@
+# LiDAR and Camera Image Recognition
+
+Reproducible code companion for:
+
+> Quito, B. and Esmahi, L. (2023). “Compare and Contrast LiDAR and Non-LiDAR
+> Technology in an Autonomous Vehicle: Developing a Safety Framework.”
+> *Open Journal of Safety Science and Technology*, 13, 101–131.
+> [https://doi.org/10.4236/ojsst.2023.133006](https://doi.org/10.4236/ojsst.2023.133006)
+
+The project reconstructs the executable parts of the paper and separates them
+from the proposed (not yet completed) vehicle experiment.
+
+## What is reproduced
+
+| Paper component | Package command | Output |
+|---|---|---|
+| 28 × 28 CNN on MNIST | `image-recognition train-mnist` | Saved model, metrics, history, and accuracy/loss plots |
+| ImageNet VGG16 inference | `image-recognition predict-vgg16` | Top-k labels and probabilities for an input image |
+| LiDAR/camera safety framework | `image-recognition safety` | Blank 25-run protocol and aggregated weather results |
+
+The MNIST network follows the architecture in sections 3.6.1–3.6.4: two
+5 × 5 convolution layers (32 and 64 filters), max pooling, a 1,024-unit dense
+layer, and a 10-class output. It contains 3,274,634 trainable parameters when
+dropout is disabled, matching the paper.
+
+The VGG16 script follows sections 3.7–3.8: resize to 224 × 224, apply Keras'
+VGG16 preprocessing, use ImageNet weights, and decode the ten most likely
+classes.
+
+## Important interpretation
+
+The paper reports several different numbers:
+
+- **99.29%** is the reported MNIST evaluation accuracy after 25 epochs.
+- **94.63%** is the top prediction probability for one bee photograph using
+  pretrained VGG16. It is a confidence score for one sample, not a dataset
+  accuracy and not a comparison of LiDAR against camera data.
+- The LiDAR/camera weather tables are an experimental proposal. No completed
+  sensor dataset or table values are published in the paper.
+
+Accordingly, this repository does not claim to reproduce a measured 94.63%
+LiDAR-vs-camera result. Exact floating-point results can vary by platform,
+TensorFlow version, initialization, and the input image.
+
+## Setup
+
+The paper used Python 3.10.4 and TensorFlow. A clean Python 3.10 environment is
+recommended.
+
+```bash
+python3.10 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install .
+```
+
+For development, use an editable installation so source changes are immediately
+available:
+
+```bash
+python -m pip install --editable .
+```
+
+Verify the installed package and command:
+
+```bash
+python -c "import image_recognition; print(image_recognition.__version__)"
+image-recognition --help
+```
+
+## Run the MNIST experiment
+
+Full 25-epoch reproduction:
+
+```bash
+image-recognition train-mnist --epochs 25 --output-dir artifacts/mnist
+```
+
+Optional dropout enhancement described in section 3.6.5:
+
+```bash
+image-recognition train-mnist --epochs 25 --dropout 0.5 \
+  --output-dir artifacts/mnist-dropout
+```
+
+For a quick pipeline check:
+
+```bash
+image-recognition train-mnist --epochs 1 --train-limit 2048 --test-limit 512 \
+  --output-dir artifacts/smoke
+```
+
+Each run writes `model.keras`, `metrics.json`, `history.csv`,
+`training_curves.png`, and `model_summary.txt`.
+
+## Run VGG16 inference
+
+```bash
+image-recognition predict-vgg16 path/to/image.jpg --top 10 \
+  --output artifacts/vgg16-prediction.json
+```
+
+The ImageNet weights download automatically on first use. To revisit the bee
+example, supply a bee image whose reuse rights you have; the original image is
+not distributed with the article.
+
+## Use the safety-framework scaffold
+
+Create a protocol with 25 runs for each combination of driver mode,
+technology, and weather condition:
+
+```bash
+image-recognition safety init data/safety_runs.csv --runs 25
+```
+
+Fill the measurement columns in the CSV, then aggregate results:
+
+```bash
+image-recognition safety summarize data/safety_runs.csv \
+  --output artifacts/safety_summary.csv
+```
+
+The long-form protocol captures accuracy, confidence, latency, obstacle
+detection, stopping distance, and notes. These fields support the paper's
+proposed extensions while keeping missing measurements blank.
+
+The prose names six conditions: sunny (`S`), cloudy (`C`), daytime rain
+(`DR`), fog (`F`), nighttime rain (`NR`), and snow (`SW`). Tables 3–6 also
+contain an unexplained `R` column. The scaffold preserves `R` as `rain` so the
+published table layout can be represented without silently discarding it.
+
+## Tests
+
+The lightweight tests do not download datasets or TensorFlow weights:
+
+```bash
+python -m unittest -v
+python -m compileall -q src
+```
+
+GitHub Actions runs these packaging checks automatically on every push and pull
+request. The original root-level Python scripts remain available as
+backward-compatible wrappers.
+
+## Published reproduction
+
+The verified 25-epoch run reached 99.20% test accuracy. See [RESULTS.md](RESULTS.md)
+for the environment, comparison with the paper, raw metrics, and curves.
+
+## Reproducibility boundary
+
+This code reproduces the published software procedures as closely as the paper
+allows. A direct LiDAR-versus-camera safety comparison still requires paired,
+time-synchronized sensor captures, ground-truth labels, weather metadata, and
+the 25 physical runs per condition proposed in section 4. Those data are not
+included in the publication.

lidar_camera_image_recognition-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+license = "MIT"
+name = "lidar-camera-image-recognition"
+version = "0.1.0"
+description = "Reproducible CNN, VGG16, and AV safety-framework experiments"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "Benjamin Quito" },
+  { name = "Larbi Esmahi" },
+]
+keywords = [
+  "computer-vision",
+  "image-classification",
+  "lidar",
+  "autonomous-vehicles",
+  "reproducible-research",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Education",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "tensorflow>=2.16,<2.17",
+  "numpy>=1.26,<2",
+  "matplotlib>=3.8,<3.9",
+  "Pillow>=10.3,<11",
+]
+
+[project.scripts]
+image-recognition = "image_recognition.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/benjaminquito/ImageRecognition"
+Repository = "https://github.com/benjaminquito/ImageRecognition"
+Paper = "https://doi.org/10.4236/ojsst.2023.133006"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+

lidar_camera_image_recognition-0.1.0/setup.cfg

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

lidar_camera_image_recognition-0.1.0/src/image_recognition/__init__.py

@@ -0,0 +1,8 @@
+"""Reproducible image-recognition experiments for autonomous-vehicle research."""
+
+from .model import build_paper_cnn
+from .safety import create_protocol, summarize
+
+__all__ = ["build_paper_cnn", "create_protocol", "summarize"]
+__version__ = "0.1.0"
+

lidar_camera_image_recognition-0.1.0/src/image_recognition/__main__.py

@@ -0,0 +1,6 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()
+

lidar_camera_image_recognition-0.1.0/src/image_recognition/cli.py

@@ -0,0 +1,45 @@
+"""Unified command-line interface for the research package."""
+
+from __future__ import annotations
+
+import argparse
+from typing import Sequence
+
+from . import __version__
+
+
+COMMANDS = {
+    "train-mnist": "Train and evaluate the paper's MNIST CNN",
+    "predict-vgg16": "Classify an image with ImageNet-pretrained VGG16",
+    "safety": "Create or summarize the AV safety-study protocol",
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="image-recognition",
+        description="Reproduce the paper's image-recognition experiments.",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument("command", nargs="?", choices=COMMANDS)
+    parser.add_argument("arguments", nargs=argparse.REMAINDER)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command is None:
+        parser.print_help()
+        print("\ncommands:")
+        for command, description in COMMANDS.items():
+            print(f"  {command:<15} {description}")
+        return 0
+    if args.command == "train-mnist":
+        from .mnist import main as command_main
+    elif args.command == "predict-vgg16":
+        from .vgg16 import main as command_main
+    else:
+        from .safety import main as command_main
+    return command_main(args.arguments)
+

lidar_camera_image_recognition-0.1.0/src/image_recognition/mnist.py

@@ -0,0 +1,147 @@
+"""Training workflow for the paper's MNIST convolutional network."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import io
+import json
+import os
+import random
+from pathlib import Path
+from typing import Sequence
+
+import numpy as np
+
+from .model import build_paper_cnn
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--epochs", type=int, default=25)
+    parser.add_argument("--batch-size", type=int, default=128)
+    parser.add_argument("--dropout", type=float, default=0.0)
+    parser.add_argument("--seed", type=int, default=42)
+    parser.add_argument("--train-limit", type=int)
+    parser.add_argument("--test-limit", type=int)
+    parser.add_argument("--output-dir", type=Path, default=Path("artifacts/mnist"))
+    return parser
+
+
+def set_reproducible_seed(seed: int) -> None:
+    os.environ.setdefault("TF_DETERMINISTIC_OPS", "1")
+    random.seed(seed)
+    np.random.seed(seed)
+    import tensorflow as tf
+
+    tf.random.set_seed(seed)
+
+
+def prepare_mnist(train_limit: int | None, test_limit: int | None):
+    from tensorflow import keras
+
+    (x_train, y_train), (x_test, y_test) = keras.datasets.mnist.load_data()
+    if train_limit is not None:
+        x_train, y_train = x_train[:train_limit], y_train[:train_limit]
+    if test_limit is not None:
+        x_test, y_test = x_test[:test_limit], y_test[:test_limit]
+
+    x_train = x_train.astype("float32")[..., np.newaxis] / 255.0
+    x_test = x_test.astype("float32")[..., np.newaxis] / 255.0
+    y_train = keras.utils.to_categorical(y_train, 10)
+    y_test = keras.utils.to_categorical(y_test, 10)
+    return (x_train, y_train), (x_test, y_test)
+
+
+def save_history(history: dict[str, list[float]], path: Path) -> None:
+    columns = list(history)
+    with path.open("w", newline="", encoding="utf-8") as stream:
+        writer = csv.DictWriter(stream, fieldnames=["epoch", *columns])
+        writer.writeheader()
+        for epoch in range(len(history[columns[0]])):
+            row = {name: history[name][epoch] for name in columns}
+            writer.writerow({"epoch": epoch + 1, **row})
+
+
+def save_curves(history: dict[str, list[float]], path: Path) -> None:
+    import matplotlib
+
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    epochs = range(1, len(history["loss"]) + 1)
+    figure, axes = plt.subplots(1, 2, figsize=(11, 4.5))
+    axes[0].plot(epochs, history["accuracy"], label="training")
+    axes[0].plot(epochs, history["val_accuracy"], label="validation")
+    axes[0].set(title="Accuracy", xlabel="Epoch", ylabel="Accuracy")
+    axes[0].legend()
+    axes[0].grid(alpha=0.25)
+    axes[1].plot(epochs, history["loss"], label="training")
+    axes[1].plot(epochs, history["val_loss"], label="validation")
+    axes[1].set(title="Loss", xlabel="Epoch", ylabel="Categorical cross-entropy")
+    axes[1].legend()
+    axes[1].grid(alpha=0.25)
+    figure.tight_layout()
+    figure.savefig(path, dpi=160)
+    plt.close(figure)
+
+
+def run(args: argparse.Namespace) -> dict[str, object]:
+    if args.epochs < 1 or args.batch_size < 1:
+        raise ValueError("epochs and batch size must be positive")
+
+    set_reproducible_seed(args.seed)
+    (x_train, y_train), (x_test, y_test) = prepare_mnist(
+        args.train_limit, args.test_limit
+    )
+    model = build_paper_cnn(dropout=args.dropout)
+
+    output_dir = args.output_dir
+    output_dir.mkdir(parents=True, exist_ok=True)
+    summary = io.StringIO()
+    model.summary(print_fn=lambda line: summary.write(line + "\n"))
+    (output_dir / "model_summary.txt").write_text(summary.getvalue(), encoding="utf-8")
+
+    trained = model.fit(
+        x_train,
+        y_train,
+        validation_data=(x_test, y_test),
+        epochs=args.epochs,
+        batch_size=args.batch_size,
+        verbose=2,
+    )
+    test_loss, test_accuracy = model.evaluate(x_test, y_test, verbose=0)
+    model.save(output_dir / "model.keras")
+    save_history(trained.history, output_dir / "history.csv")
+    save_curves(trained.history, output_dir / "training_curves.png")
+
+    metrics = {
+        "test_loss": float(test_loss),
+        "test_accuracy": float(test_accuracy),
+        "epochs": args.epochs,
+        "batch_size": args.batch_size,
+        "dropout": args.dropout,
+        "seed": args.seed,
+        "training_samples": int(len(x_train)),
+        "test_samples": int(len(x_test)),
+        "trainable_parameters": int(model.count_params()),
+    }
+    (output_dir / "metrics.json").write_text(
+        json.dumps(metrics, indent=2) + "\n", encoding="utf-8"
+    )
+    return metrics
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        metrics = run(args)
+    except ValueError as error:
+        build_parser().error(str(error))
+    print(json.dumps(metrics, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

lidar_camera_image_recognition-0.1.0/src/image_recognition/model.py

@@ -0,0 +1,41 @@
+"""Neural-network definitions reconstructed from the paper."""
+
+from __future__ import annotations
+
+
+def build_paper_cnn(dropout: float = 0.0):
+    """Build the 28x28 CNN described in sections 3.6.1-3.6.4.
+
+    TensorFlow is imported lazily so metadata and safety utilities remain
+    usable without initializing the ML runtime.
+    """
+    if not 0.0 <= dropout < 1.0:
+        raise ValueError("dropout must be in the interval [0, 1)")
+
+    from tensorflow import keras
+
+    layers = [
+        keras.layers.Input(shape=(28, 28, 1), name="image"),
+        keras.layers.Conv2D(
+            32, kernel_size=(5, 5), padding="same", activation="relu"
+        ),
+        keras.layers.MaxPooling2D(pool_size=(2, 2)),
+        keras.layers.Conv2D(
+            64, kernel_size=(5, 5), padding="same", activation="relu"
+        ),
+        keras.layers.MaxPooling2D(pool_size=(2, 2)),
+        keras.layers.Flatten(),
+        keras.layers.Dense(1024, activation="relu"),
+    ]
+    if dropout:
+        layers.append(keras.layers.Dropout(dropout))
+    layers.append(keras.layers.Dense(10, activation="softmax"))
+
+    model = keras.Sequential(layers, name="paper_mnist_cnn")
+    model.compile(
+        optimizer="adam",
+        loss="categorical_crossentropy",
+        metrics=["accuracy"],
+    )
+    return model
+

lidar_camera_image_recognition-0.1.0/src/image_recognition/safety.py

@@ -0,0 +1,167 @@
+"""Create and summarize the paper's proposed AV safety-study protocol."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import statistics
+from collections import defaultdict
+from pathlib import Path
+from typing import Sequence
+
+
+WEATHER = {
+    "S": "sunny",
+    "C": "cloudy",
+    "R": "rain (table-only code)",
+    "F": "foggy",
+    "DR": "daytime rainy",
+    "NR": "nighttime rainy",
+    "SW": "snowy",
+}
+TECHNOLOGIES = ("lidar", "camera")
+DRIVER_MODES = ("human", "autonomous")
+FIELDS = (
+    "driver_mode",
+    "technology",
+    "weather_code",
+    "weather",
+    "run",
+    "expected_label",
+    "predicted_label",
+    "confidence",
+    "latency_ms",
+    "obstacle_detected",
+    "stopping_distance_m",
+    "notes",
+)
+
+
+def create_protocol(path: Path, runs: int = 25) -> int:
+    """Write a blank long-form experimental protocol and return its row count."""
+    if runs < 1:
+        raise ValueError("runs must be positive")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    count = 0
+    with path.open("w", newline="", encoding="utf-8") as stream:
+        writer = csv.DictWriter(stream, fieldnames=FIELDS)
+        writer.writeheader()
+        for driver_mode in DRIVER_MODES:
+            for technology in TECHNOLOGIES:
+                for code, weather in WEATHER.items():
+                    for run_number in range(1, runs + 1):
+                        writer.writerow(
+                            {
+                                "driver_mode": driver_mode,
+                                "technology": technology,
+                                "weather_code": code,
+                                "weather": weather,
+                                "run": run_number,
+                            }
+                        )
+                        count += 1
+    return count
+
+
+def _optional_float(value: str) -> float | None:
+    value = value.strip()
+    return float(value) if value else None
+
+
+def _optional_correct(expected: str, predicted: str) -> float | None:
+    expected, predicted = expected.strip(), predicted.strip()
+    if not expected or not predicted:
+        return None
+    return float(expected == predicted)
+
+
+def _mean(values: list[float]) -> str:
+    return f"{statistics.fmean(values):.6f}" if values else ""
+
+
+def summarize(source: Path, destination: Path) -> int:
+    """Aggregate populated measurements and return the number of groups."""
+    grouped: dict[tuple[str, str, str], dict[str, list[float]]] = defaultdict(
+        lambda: defaultdict(list)
+    )
+    with source.open(newline="", encoding="utf-8") as stream:
+        reader = csv.DictReader(stream)
+        missing = set(FIELDS) - set(reader.fieldnames or ())
+        if missing:
+            raise ValueError(f"missing columns: {', '.join(sorted(missing))}")
+        for row in reader:
+            key = (row["driver_mode"], row["technology"], row["weather_code"])
+            values = {
+                "accuracy": _optional_correct(
+                    row["expected_label"], row["predicted_label"]
+                ),
+                "confidence": _optional_float(row["confidence"]),
+                "latency_ms": _optional_float(row["latency_ms"]),
+                "stopping_distance_m": _optional_float(row["stopping_distance_m"]),
+            }
+            for name, value in values.items():
+                if value is not None:
+                    grouped[key][name].append(value)
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    output_fields = (
+        "driver_mode",
+        "technology",
+        "weather_code",
+        "weather",
+        "labeled_samples",
+        "accuracy",
+        "mean_confidence",
+        "mean_latency_ms",
+        "mean_stopping_distance_m",
+    )
+    with destination.open("w", newline="", encoding="utf-8") as stream:
+        writer = csv.DictWriter(stream, fieldnames=output_fields)
+        writer.writeheader()
+        for key in sorted(grouped):
+            driver_mode, technology, code = key
+            values = grouped[key]
+            writer.writerow(
+                {
+                    "driver_mode": driver_mode,
+                    "technology": technology,
+                    "weather_code": code,
+                    "weather": WEATHER.get(code, "unknown"),
+                    "labeled_samples": len(values["accuracy"]),
+                    "accuracy": _mean(values["accuracy"]),
+                    "mean_confidence": _mean(values["confidence"]),
+                    "mean_latency_ms": _mean(values["latency_ms"]),
+                    "mean_stopping_distance_m": _mean(
+                        values["stopping_distance_m"]
+                    ),
+                }
+            )
+    return len(grouped)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    commands = parser.add_subparsers(dest="command", required=True)
+    initialize = commands.add_parser("init", help="create a blank study protocol")
+    initialize.add_argument("output", type=Path)
+    initialize.add_argument("--runs", type=int, default=25)
+    aggregate = commands.add_parser("summarize", help="aggregate completed runs")
+    aggregate.add_argument("source", type=Path)
+    aggregate.add_argument("--output", type=Path, required=True)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "init":
+        rows = create_protocol(args.output, args.runs)
+        print(f"Created {rows} protocol rows at {args.output}")
+    else:
+        groups = summarize(args.source, args.output)
+        print(f"Wrote {groups} populated groups to {args.output}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

lidar_camera_image_recognition-0.1.0/src/image_recognition/vgg16.py

@@ -0,0 +1,65 @@
+"""ImageNet-pretrained VGG16 inference."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Sequence
+
+import numpy as np
+
+
+def predict(image_path: Path, top: int = 10) -> list[dict[str, object]]:
+    """Return the top ImageNet predictions for one image."""
+    if not image_path.is_file():
+        raise FileNotFoundError(image_path)
+    if not 1 <= top <= 1000:
+        raise ValueError("top must be between 1 and 1000")
+
+    from tensorflow.keras.applications.vgg16 import (
+        VGG16,
+        decode_predictions,
+        preprocess_input,
+    )
+    from tensorflow.keras.utils import img_to_array, load_img
+
+    image = load_img(image_path, target_size=(224, 224))
+    batch = np.expand_dims(img_to_array(image), axis=0)
+    probabilities = VGG16(weights="imagenet").predict(
+        preprocess_input(batch), verbose=0
+    )
+    decoded = decode_predictions(probabilities, top=top)[0]
+    return [
+        {"synset": synset, "label": label, "probability": float(probability)}
+        for synset, label, probability in decoded
+    ]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("image", type=Path)
+    parser.add_argument("--top", type=int, default=10)
+    parser.add_argument("--output", type=Path)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    results = {
+        "image": str(args.image),
+        "model": "VGG16",
+        "weights": "ImageNet",
+        "predictions": predict(args.image, args.top),
+    }
+    rendered = json.dumps(results, indent=2) + "\n"
+    if args.output:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(rendered, encoding="utf-8")
+    print(rendered, end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

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

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: lidar-camera-image-recognition
+Version: 0.1.0
+Summary: Reproducible CNN, VGG16, and AV safety-framework experiments
+Author: Benjamin Quito, Larbi Esmahi
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/benjaminquito/ImageRecognition
+Project-URL: Repository, https://github.com/benjaminquito/ImageRecognition
+Project-URL: Paper, https://doi.org/10.4236/ojsst.2023.133006
+Keywords: computer-vision,image-classification,lidar,autonomous-vehicles,reproducible-research
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: tensorflow<2.17,>=2.16
+Requires-Dist: numpy<2,>=1.26
+Requires-Dist: matplotlib<3.9,>=3.8
+Requires-Dist: Pillow<11,>=10.3
+Dynamic: license-file
+
+# LiDAR and Camera Image Recognition
+
+Reproducible code companion for:
+
+> Quito, B. and Esmahi, L. (2023). “Compare and Contrast LiDAR and Non-LiDAR
+> Technology in an Autonomous Vehicle: Developing a Safety Framework.”
+> *Open Journal of Safety Science and Technology*, 13, 101–131.
+> [https://doi.org/10.4236/ojsst.2023.133006](https://doi.org/10.4236/ojsst.2023.133006)
+
+The project reconstructs the executable parts of the paper and separates them
+from the proposed (not yet completed) vehicle experiment.
+
+## What is reproduced
+
+| Paper component | Package command | Output |
+|---|---|---|
+| 28 × 28 CNN on MNIST | `image-recognition train-mnist` | Saved model, metrics, history, and accuracy/loss plots |
+| ImageNet VGG16 inference | `image-recognition predict-vgg16` | Top-k labels and probabilities for an input image |
+| LiDAR/camera safety framework | `image-recognition safety` | Blank 25-run protocol and aggregated weather results |
+
+The MNIST network follows the architecture in sections 3.6.1–3.6.4: two
+5 × 5 convolution layers (32 and 64 filters), max pooling, a 1,024-unit dense
+layer, and a 10-class output. It contains 3,274,634 trainable parameters when
+dropout is disabled, matching the paper.
+
+The VGG16 script follows sections 3.7–3.8: resize to 224 × 224, apply Keras'
+VGG16 preprocessing, use ImageNet weights, and decode the ten most likely
+classes.
+
+## Important interpretation
+
+The paper reports several different numbers:
+
+- **99.29%** is the reported MNIST evaluation accuracy after 25 epochs.
+- **94.63%** is the top prediction probability for one bee photograph using
+  pretrained VGG16. It is a confidence score for one sample, not a dataset
+  accuracy and not a comparison of LiDAR against camera data.
+- The LiDAR/camera weather tables are an experimental proposal. No completed
+  sensor dataset or table values are published in the paper.
+
+Accordingly, this repository does not claim to reproduce a measured 94.63%
+LiDAR-vs-camera result. Exact floating-point results can vary by platform,
+TensorFlow version, initialization, and the input image.
+
+## Setup
+
+The paper used Python 3.10.4 and TensorFlow. A clean Python 3.10 environment is
+recommended.
+
+```bash
+python3.10 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install .
+```
+
+For development, use an editable installation so source changes are immediately
+available:
+
+```bash
+python -m pip install --editable .
+```
+
+Verify the installed package and command:
+
+```bash
+python -c "import image_recognition; print(image_recognition.__version__)"
+image-recognition --help
+```
+
+## Run the MNIST experiment
+
+Full 25-epoch reproduction:
+
+```bash
+image-recognition train-mnist --epochs 25 --output-dir artifacts/mnist
+```
+
+Optional dropout enhancement described in section 3.6.5:
+
+```bash
+image-recognition train-mnist --epochs 25 --dropout 0.5 \
+  --output-dir artifacts/mnist-dropout
+```
+
+For a quick pipeline check:
+
+```bash
+image-recognition train-mnist --epochs 1 --train-limit 2048 --test-limit 512 \
+  --output-dir artifacts/smoke
+```
+
+Each run writes `model.keras`, `metrics.json`, `history.csv`,
+`training_curves.png`, and `model_summary.txt`.
+
+## Run VGG16 inference
+
+```bash
+image-recognition predict-vgg16 path/to/image.jpg --top 10 \
+  --output artifacts/vgg16-prediction.json
+```
+
+The ImageNet weights download automatically on first use. To revisit the bee
+example, supply a bee image whose reuse rights you have; the original image is
+not distributed with the article.
+
+## Use the safety-framework scaffold
+
+Create a protocol with 25 runs for each combination of driver mode,
+technology, and weather condition:
+
+```bash
+image-recognition safety init data/safety_runs.csv --runs 25
+```
+
+Fill the measurement columns in the CSV, then aggregate results:
+
+```bash
+image-recognition safety summarize data/safety_runs.csv \
+  --output artifacts/safety_summary.csv
+```
+
+The long-form protocol captures accuracy, confidence, latency, obstacle
+detection, stopping distance, and notes. These fields support the paper's
+proposed extensions while keeping missing measurements blank.
+
+The prose names six conditions: sunny (`S`), cloudy (`C`), daytime rain
+(`DR`), fog (`F`), nighttime rain (`NR`), and snow (`SW`). Tables 3–6 also
+contain an unexplained `R` column. The scaffold preserves `R` as `rain` so the
+published table layout can be represented without silently discarding it.
+
+## Tests
+
+The lightweight tests do not download datasets or TensorFlow weights:
+
+```bash
+python -m unittest -v
+python -m compileall -q src
+```
+
+GitHub Actions runs these packaging checks automatically on every push and pull
+request. The original root-level Python scripts remain available as
+backward-compatible wrappers.
+
+## Published reproduction
+
+The verified 25-epoch run reached 99.20% test accuracy. See [RESULTS.md](RESULTS.md)
+for the environment, comparison with the paper, raw metrics, and curves.
+
+## Reproducibility boundary
+
+This code reproduces the published software procedures as closely as the paper
+allows. A direct LiDAR-versus-camera safety comparison still requires paired,
+time-synchronized sensor captures, ground-truth labels, weather metadata, and
+the 25 physical runs per condition proposed in section 4. Those data are not
+included in the publication.

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

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/image_recognition/__init__.py
+src/image_recognition/__main__.py
+src/image_recognition/cli.py
+src/image_recognition/mnist.py
+src/image_recognition/model.py
+src/image_recognition/safety.py
+src/image_recognition/vgg16.py
+src/lidar_camera_image_recognition.egg-info/PKG-INFO
+src/lidar_camera_image_recognition.egg-info/SOURCES.txt
+src/lidar_camera_image_recognition.egg-info/dependency_links.txt
+src/lidar_camera_image_recognition.egg-info/entry_points.txt
+src/lidar_camera_image_recognition.egg-info/requires.txt
+src/lidar_camera_image_recognition.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

lidar_camera_image_recognition-0.1.0/src/lidar_camera_image_recognition.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+image-recognition = image_recognition.cli:main

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

@@ -0,0 +1,4 @@
+tensorflow<2.17,>=2.16
+numpy<2,>=1.26
+matplotlib<3.9,>=3.8
+Pillow<11,>=10.3

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

@@ -0,0 +1 @@
+image_recognition