[Enhancement/Bug] Streamline Tutorial Onboarding and Resolve Silent Inference Failures

[iocalangiu]

The current tutorial_image_segmentation.ipynb has a high barrier to entry and fails silently on specific local environments.

1. Massive Data Overhead: The requirement to download 10GB of data just to verify the pipeline works is a major blockage. It often triggers Google Drive download limits and discourages quick testing.

2. Silent Inference Failure: On certain Intel-based hardware (MacBook Pro 2016), the model runs without errors but produces an all-zero prediction mask. I checked whether the weights are loaded normally (they seem fine) and the range of input values (0-255).

Prediction  is 0s 

     Weights are OK	

   Input values are OK

3. Environment Incompatibility: The notebook fails in Google Colab due to a version mismatch with numpy, Colab comes with numpy > 2.2.x while perceptionmetrics requires 1.26.2.

SOLUTIONS:
I propose updating the tutorial with the following improvements:

1. "Quick Start" Mode (Sample Dataset)
Introduce a v_small dataset option. I would introduce a curated set of 5–10 images instead of the full 10GB. Users can verify their environment and the inference logic in under 60 seconds.
3. Robust Environment Support (Colab & NumPy)
Here I am still working on finding the right combination. Colab's environment update to NumPy 2.x breaks backward compatibility with the current requirement of 1.26.2.
Plus, here I would add instructions on how to create a mount such that users don't need to download the data every time.

[dpascualhe]

Good proposal! Regarding the dataset, you can share it with me and I'll upload it to our org drive or something. Also I think this new 'quick start' notebook shouldn't replace the one with RELLIS-3D, but it might be more suitable as a entrypoint in the docs. Regarding numpy, I think there was some incompatibility of 2.x versions with some other dependencies we are using in combination with perceptionmetrics (mmdetection3d/mmsegmentation), so I would try to keep 1.26.2.

[iocalangiu]

I wasn't super clear. I'm not saying to touch any of the versions. It's just when you run the notebook on Colab, which uses by default the latest versions, it will overwrite numpy 1.26.2. What I did was to run this in the beginning:

!pip uninstall -y pandas numpy pillow scipy

!pip install --upgrade --force-reinstall \
    "numpy==1.26.4" \
    "pandas==2.2.3" \
    "pillow==12.1.0" \
    "scipy==1.12.0" \
    "gdown" \
    "pyarrow>=18.0.0" \
    "matplotlib>=3.6.0" \
    "opencv-python-headless>=4.10.0.84"

So I will work on 2 new notebooks: 1) quick start (same as the RELLIS-3D, but smaller sample - will send data shortly to you) and 2) quick start on Google Colab.

[dpascualhe]

great! I think we can keep a single "quick start" notebook. How are you installing dependencies in google collab? Now that the pip package is available, could you simply do pip install perceptionmetrics in the first notebook cell?

[iocalangiu]

If you just do pip install perceptionmetricsit will throw an error because it will try to use the latest numpy and ignore the numpy in your package. So what I did was to:

1. uninstall numpy and a few other packages;
2. install the versions you have listed in the poetry file;
3. pip install perceptionmetrics;