Fix read_file for shapefiles without image_path/label columns (#997)

[SuMayaBee]

Description

Allow users to pass image_path and label arguments to read_file() when reading shapefiles that don't have these columns.

Problem

When users have a shapefile without image_path or label columns, read_file() crashes with:

ValueError: No image_path column found in shapefile, please specify rgb path

Solution

1. Pass image_path argument to shapefile_to_annotations() - Modified utilities.py to forward the image_path argument when reading shapefiles.

2. Add warning when image_path is passed - Users see a warning confirming the value will be assigned to every row.

3. Allow label argument - Removed blocking error for missing label column. Now defaults to "Unknown" if not provided.

4. Write tests for shapefiles - Added 4 tests covering all scenarios.

5. Add documentation example - Added example in docs/user_guide/01_Reading_data.md with argument table showing required vs optional parameters.

Before & After

For shapefiles without image_path and label columns:

#	Scenario	Before	After
1	Pass only image_path argument	❌ ValueError	✅ Works, label defaults to "Unknown"
2	Pass both image_path and label arguments	❌ ValueError	✅ Works

For shapefiles with image_path and label columns:

#	Scenario	Before	After
1	No arguments passed	✅ Works	✅ Works (reads from columns)
2	Pass image_path argument	✅ Works	✅ Works (uses argument, overrides column)
3	Pass label argument	✅ Works	✅ Works (uses argument, overrides column)
4	Pass both arguments	✅ Works	✅ Works (uses arguments, overrides columns)

Usage Improvement

Previously (workaround):

raster_path = "/path/to/image.tif"
gdf = gpd.read_file("/path/to/annotations.shp")
gdf["image_path"] = os.path.basename(raster_path)
gdf["label"] = "Tree"
ground_truth = read_file(gdf, root_dir=os.path.dirname(raster_path))

This required two extra library imports (os and geopandas).

Now:

ground_truth = read_file("/path/to/annotations.shp", image_path="/path/to/image.tif", label="Tree")

No extra library imports needed. Here, root_dir is optional when image_path is a full path. label is optional too and defaults to "Unknown" when not provided.

Related Issue(s)

Closes #997

AI-Assisted Development

• I used AI tools (e.g., GitHub Copilot, ChatGPT, etc.) in developing this PR
• I understand all the code I'm submitting

[codecov]

Codecov Report

❌ Patch coverage is 33.33333% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.98%. Comparing base (7036fa9) to head (1f1348a).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
src/deepforest/utilities.py	33.33%	2 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1242   +/-   ##
=======================================
  Coverage   86.97%   86.98%           
=======================================
  Files          24       24           
  Lines        3009     3011    +2     
=======================================
+ Hits         2617     2619    +2     
  Misses        392      392           

Flag	Coverage Δ
unittests	86.98% <33.33%> (+<0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jveitchmichaelis]

Thanks for the contribution. A couple of comments on the tests, there is quite a lot of duplicate code and perhaps it would be better to use pytest fixtures for some of the input data?

Please could you also include the AI assistance declaration from the PR template? (you can see an example here)

[SuMayaBee]

@jveitchmichaelis Thanks for the feedback! I've addressed both points:

1. Refactored the tests to use a sample_shapefile_gdf pytest fixture to eliminate duplicate code
2. Added the AI assistance declaration to the PR description

[henrykironde]

@SuMayaBee Thanks for your perspective on the issue. The function you’re modifying has changed; could you rebase and update this PR so we can confirm whether these changes are still needed?

[SuMayaBee]

@henrykironde Thanks! I've rebased onto upstream/main and updated the implementation to work with the new function structure. The changes are still needed - I've integrated them and fixed a bug where label override wasn't being applied. All tests pass. Ready for review!

[SuMayaBee]

Hi @henrykironde! Just a quick follow-up on this. I’ve rebased and updated the implementation as discussed. Whenever you have a moment, I’d love to get your thoughts so we can move this forward.