Skip to content

feat: support tag_depth > 1 in add_images_from_path - #1775

Open
lorinczszabolcs wants to merge 4 commits into
lightly-ai:mainfrom
lorinczszabolcs:feat/tag-depth-multi-level
Open

feat: support tag_depth > 1 in add_images_from_path#1775
lorinczszabolcs wants to merge 4 commits into
lightly-ai:mainfrom
lorinczszabolcs:feat/tag-depth-multi-level

Conversation

@lorinczszabolcs

@lorinczszabolcs lorinczszabolcs commented Jul 24, 2026

Copy link
Copy Markdown

What has changed and why?

add_images_from_path only supported tag_depth=1 (added in #84). This generalizes it to tag_depth=N: each image is tagged with its first N folder levels below the loaded path (fewer if nested less deeply), so it can get several tags. tag_depth=0 still skips tagging; negative values now raise ValueError. Docstrings, docs and changelog updated. No new dependencies.

Requested in comment, which also suggested extending tag_depth to the YOLO/COCO loaders, those are left for a separate PR.

How has it been tested?

New unit tests in tests/core/image/test_add_images.py for tag_depth=2 and the negative case; existing tag_depth=0/1 and file-URL tests still pass.

cd lightly_studio
uv run pytest tests/core/image/test_add_images.py -k tag_depth

Did you update CHANGELOG.md?

  • Yes
  • Not needed (internal change)

Summary by CodeRabbit

  • New Features
    • Image imports now support automatic tagging across multiple folder levels (including tag_depth > 1).
    • tag_depth=0 disables folder-based tagging; tags can be derived from the first N directory levels beneath the selected path.
  • Documentation
    • Updated tagging and dataset setup guides, including clarified tag_depth behavior and nested-folder examples.
    • Changelog updated to reflect the expanded multi-level tagging.
  • Bug Fixes
    • Fixed folder-based tag derivation for nested image directories to match the documented behavior.
  • Tests
    • Added coverage for rejecting negative tag_depth and validating tag_depth=2.

Generalize tag_samples_by_directory to tag samples by the first N
directory levels below the loaded path (previously only tag_depth=1 was
supported) and raise ValueError on a negative tag_depth. Update the
docstring, docs and changelog, and add tests for tag_depth=2 and the
negative case.
@lorinczszabolcs
lorinczszabolcs requested a review from a team as a code owner July 24, 2026 16:50
@CLAassistant

CLAassistant commented Jul 24, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@coderabbitai

coderabbitai Bot commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 20c966f4-bebe-4d27-b240-793c2c1339ba

📥 Commits

Reviewing files that changed from the base of the PR and between 051987f and 590cc97.

📒 Files selected for processing (1)
  • CHANGELOG.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • CHANGELOG.md

📝 Walkthrough

Walkthrough

tag_samples_by_directory now supports tagging images from multiple directory levels, rejects negative depths, and preserves no-tag behavior for root-level images. Related API documentation, conceptual tagging guidance, changelog text, and tests were updated.

Changes

Image directory tagging

Layer / File(s) Summary
Multi-level tagging implementation
lightly_studio/src/lightly_studio/core/image/add_images.py, lightly_studio/src/lightly_studio/core/image/image_dataset.py
tag_depth accepts non-negative values, tags images from up to the first N directory levels, and documents the updated behavior and errors.
Tagging validation and documentation
lightly_studio/tests/core/image/test_add_images.py, lightly_studio/tests/core/image/test_image_dataset__path.py, lightly_studio/docs/docs/concepts_and_tools/tags.md, lightly_studio/docs/docs/dataset_setup/image_dataset.md, CHANGELOG.md
Tests cover negative depths, tag_depth=2, nested paths, and root-level images; documentation and the changelog describe multi-level tagging.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title is concise and accurately summarizes the main change: extending add_images_from_path to support tag_depth values greater than 1.
Description check ✅ Passed The description follows the required template and includes the change summary, testing details, and changelog confirmation.
Docstring Coverage ✅ Passed Docstring coverage is 85.71% which is sufficient. The required threshold is 80.00%.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lightly_studio/src/lightly_studio/core/image/image_dataset.py`:
- Around line 153-155: Validate negative tag_depth in the entry-point method
before loading images or performing filesystem/database work, alongside
validate_limit(). Keep the existing tag_samples_by_directory() validation so
direct callers remain protected.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: fd3dfc4b-496a-4e0d-ad31-fcb2f5d4aabe

📥 Commits

Reviewing files that changed from the base of the PR and between cbdfb05 and 3ab5ead.

📒 Files selected for processing (6)
  • CHANGELOG.md
  • lightly_studio/docs/docs/concepts_and_tools/tags.md
  • lightly_studio/docs/docs/dataset_setup/image_dataset.md
  • lightly_studio/src/lightly_studio/core/image/add_images.py
  • lightly_studio/src/lightly_studio/core/image/image_dataset.py
  • lightly_studio/tests/core/image/test_add_images.py

Comment thread lightly_studio/src/lightly_studio/core/image/image_dataset.py
lorinczszabolcs and others added 3 commits July 24, 2026 20:40
Negative tag_depth was only rejected inside tag_samples_by_directory,
which runs only when new samples are created, so an invalid depth was
silently accepted for empty or all-existing loads. Validate it in
add_images_from_path alongside validate_limit, before any filesystem or
database work, and keep the helper check for direct callers. Add a test.
@lorinczszabolcs

Copy link
Copy Markdown
Author

@MalteEbner this extends the tag_depth support you reviewed in #84 to tag_depth > 1. Tagging in case the PR didn't reach you yet.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants