Avian Visitors - Teddy Warner

[giscus[bot]]

Avian Visitors - Teddy Warner

A live bird collage from your window.

https://theodore.net/projects/AvianVisitors/

[probablyalexzhu]

that's awesome, the birds + the packing algorithm look great. thanks for sharing!

[nkumar23]

Excellent writeup! So used to seeing one-off vibe coded stuff on Twitter with no documentation, or links to sloppy repos. Appreciate the thoughtful explanation here!

[MichaelMilstead]

Really cool :). I guess it would have been so easy to have the result just be a list of bird names, but the image collage is the tweak that makes it feel really magical!
I feel like most really interesting projects have some (maybe small) twist that isn't obvious and makes the whole thing exciting.

Also, I guessed you live somewhat near me since I recognized most of your birds! Turns out we're actually not that close, these birds just mobile

[GeoNomad]

Very cool. I already have my Pi uploading to BirdWeather and to httpstate.com. I will be adding your collage to my website soon. I love it. Thanks for cleaning up the hallucinated bits.

[entername-here]

Hello! Super excited about the project, and hoping I could get some help understanding what has gone amiss. When I'm done running the script linked above, I get the stock display at http://birdnet.local/, and can only get the collage to work at http://birdnet.local/avian/frontend/index.html, though the collage doesn't seem to see any of the data that the stock display is gathering. Any tips as to what went wrong and how to repair?

[Twarner491]

Hello!! Interesting, sounds like the overlay didn't fully land.

Would you mind checking the five symlinks at the Caddy doc root:

ls -la ~/BirdSongs/Extracted/ | grep -E 'index\.html|apt\.js|masks\.json|dims\.json|^l.*avian'

You should see symlinks pointing into ~/BirdNET-Pi/avian/, missing them is one path to the stock UI showing at /.

As well as the try_files override in the Caddyfile:

sudo grep -A2 php_fastcgi /etc/caddy/Caddyfile

Look for try_files {path} {path}/index.html {path}/index.php index.php inside the php_fastcgi block - without it, Caddy serves index.php over index.html and you get the stock UI even when the symlinks exist

In either case it's worth trying:

sudo ~/BirdNET-Pi/scripts/install_services.sh
sudo ~/BirdNET-Pi/scripts/update_caddyfile.sh
sudo systemctl restart caddy

to see if it fixes itself up. The no data issue here is a symptom of the same root cause - apt.js uses realitive paths designed for serving from the index, so accessing it via /avian/frontend/ breaks URLs.

fingers crossed, but will keep an eye out for your response if you're still running into trouble! best of luck :)

[entername-here]

Thank you for the quick response! Something along the way in the above seems to have made things mostly happy. Hooray! When running the install_services.sh command I get the following:

• echo 'Unable to find a configuration file. Please make sure that /birdnet.conf exists.'
  Unable to find a configuration file. Please make sure that /birdnet.conf exists.

Despite that error, I'm now getting your collage page at http://birdnet.local/, so we're already in a much happier spot. :)

Any suggestions on fixing broken images? That may fall into the "Illustrations + Collage" section above, but about half the birds my mic is picking up are being properly identified, but no images come back. I'm in Wisconsin, so nothing too wild happening over here bird-wise, but for example something fairly common like Red-bellied Woodpecker comes back without an image. Maybe there's some scripting to run to have Gemini generate more bird images...?

Again: THANK YOU. This is a super cool project. :)

[Twarner491]

glad to hear it! The error you saw is harmless - install_services.sh inherits $my_dir from the calling installer, and sudo drops that env var when you invoke it directly, so the script bails before doing anything destructive. To safely re-run standalone trysudo -E HOME=$HOME USER=$USER ~/BirdNET-Pi/scripts/install_services.sh, but everything should be in order regardless!

As for the missing images, the repo currently ships with a bunch of Western US species (as this is where my balcony is). To fill in your Wisconsin set, use the repo's pregen.py which calls Gemini to generate illustrations. You'll need a Gemini API key which you can grab here

export GEMINI_API_KEY='your-key'
# one bird at a time:
python3 ~/BirdNET-Pi/avian/scripts/pregen.py \
  --species "Melanerpes carolinus|Red-bellied Woodpecker" --force

# or batch every species your Pi knows:
python3 ~/BirdNET-Pi/avian/scripts/pregen.py \
  --labels ~/BirdNET-Pi/model/labels.txt

I've been working to build out a much larger / more robust bundle of birds, which should cover all of North America instead of just west coast. Will be a bit longer before this goes live as I'm reviewing to make sure plumage is correct for each species, but stay tuned!

and of course :) i'm happy it's been so well recieved!

[entername-here]

Thank you again! I'll give this a whirl and see what happens. Keep up the great work!

[stonewall027]

Love this so much and also had to run those symlink commands to get things to display properly. Any chance you'd know how to make all of this properly display a dark mode like this website? Thanks again for sharing!

[Twarner491]

thanks! there's now a ‘charcoal’ theme you can toggle on in settings!

[drundoor]

Amazing project! Just pushed a fork with a safe public mirror of the main screen, 34 new birds, and mobile UI optimizations. Happy to submit as PR if you'd prefer. Thanks for all your work on this.

[absneed]

Thanks for sharing this. I've just started playing around with a Pi 4 and this has been a perfect project to start me on.

One thing I don't quite understand is how the illustration rendering works. For many of the birds the Pi has logged, I get the nice illustrated images (cutout.png), but other birds it's a picture (cutout.jpg). The .jpg image is happening for common birds in the east like a Northern Cardinal or Blue Jay.

Is that the way it's supposed to work?

[Twarner491]

of course! glad you're enjoying hacking on it :)

the repo currently ships with a predominately Western US specie bundle (as this is where my mic is!). Some of these birds span coast to coast and thus you'll see the illustrations for these species on your pi. As for the other east-cast species, you can use the repo's pregen.py which calls Gemini to generate illustrations. You'll need a Gemini API key which you can grab here

export GEMINI_API_KEY='your-key'

# render every species on a cream ground
python3
 ~/BirdNET-Pi/avian/scripts/pregen.py \
  --labels ~/BirdNET-Pi/model/labels.txt --force

# strip the ground (BiRefNet) and crop to the bird
python3
 ~/BirdNET-Pi/avian/scripts/cutout.py

# rebuild the collage silhouette masks
python3
 ~/BirdNET-Pi/avian/scripts/build_masks.py

I've been working to build out a larger library to cover all of North America but admittedly a bit birded out this week, so you'll have to stay tuned for this in the future.

[tpoindex]

Hey Teddy - cool stuff! Btw, I'm running on a spare Pi 3B+ I had otherwise just collecting dust. Seems to work Ok, if not a little slowly for now.

Another data point on some install problems, I ran into the same as @entername-here in comment #discussioncomment-17169048. Your fixes in the following comment (install_services.sh; update_caddyfile.sh; restart caddy) also worked for me. This is based on commit 9b262ff.

[adamoberley]

If you're running Home Assistant, I made this dashboard super easy to set up and add to your instance and I added a bunch of midwest bird illustrations too! https://github.com/adamoberley/HABirdDashboard

[jochter67]

Hi Teddy, nice Project.
I am trying to create the drawings for my part of the World that is Havelland in Brandenburg Germany.
I provided the Gemini Api Key and the EBird Key via export GEMINI_API_KEY='xxx' and export EBIRD_API_KEY='xxx'
So i tried your pregen.py Skript like so:
python3 ~/BirdNET-Pi/avian/scripts/pregen.py --labels ~/BirdNET-Pi/model/labels.txt --ebird-region DE-BB-HVL
[ebird] filtering 6522 species against DE-BB-HVL...
[notes] loaded per-species addenda for 19 species
generating up to 508 illustrations into /home/maui/BirdNET-Pi/avian/assets/illustrations/
[fail] accipiter-nisus.png: HTTP Error 429: Too Many Requests
[fail] accipiter-nisus-2.png: HTTP Error 429: Too Many Requests
[fail] acrocephalus-arundinaceus.png: HTTP Error 429: Too Many Requests
[fail] acrocephalus-arundinaceus-2.png: HTTP Error 429: Too Many Requests
[fail] acrocephalus-palustris.png: HTTP Error 429: Too Many Requests
[fail] acrocephalus-palustris-2.png: HTTP Error 429: Too Many Requests

But as you can see i got an Too Many Requests Error.
I lowered the default value for --sleep to 15.0 but that didn't do the trick.
I am on the free Gemini API Key.

I tried to generate a single species with
python3 ~/BirdNET-Pi/avian/scripts/pregen.py --species "accipiter-nisus|Sperber" --force
[notes] loaded per-species addenda for 19 species
generating up to 2 illustrations into /home/maui/BirdNET-Pi/avian/assets/illustrations/
[fail] accipiter-nisus.png: HTTP Error 429: Too Many Requests
[fail] accipiter-nisus-2.png: HTTP Error 429: Too Many Requests

generated 0 · skipped 0 · failed 2
first failure: accipiter-nisus.png (re-run without --force to retry only the misses)

But as you can see even that didn't work.
Any suggestions are welcome. Thank you

[ufjt78]

I stopped trying to generate images for all birds and only am generating for the ones I've detected and have missing images.

[entername-here]

Out of curiosity, did you do anything special to get your images to work? Mine all come back much larger file size and they’re not transparent. They don’t show up in the collage at all, either. :(

[Twarner491]

Hi all! thanks for digging in on this. ufjt78 is right, gemini-2.5-flash-image seems to have been moved to paid only, so the free tier's quota for it is effectively zero now and thus you need billing enabled on the key.

the key bills per image and a ~500-image set runs around $20 if you generate everything. but you almost certainly don't need to: generate only the species your Pi has actually detected and is missing art for.

regarding the large, non-transparent images: the generator is three scripts now, and pregen.py is only the first step. It renders each bird on a solid cream ground (which is exactly why yours are big and not transparent). You then run:

# remove the cream ground (BiRefNet) and crop to the bird
python3 ~/BirdNET-Pi/avian/scripts/cutout.py
# rebuild the collage silhouette masks
python3 ~/BirdNET-Pi/avian/scripts/build_masks.py

cutout.py needs a couple extra packages, so run pip install -r ~/BirdNET-Pi/avian/scripts/requirements.txt first (the first cutout also pulls down a ~1GB matting model). fair warning that the background removal is heavy on a Pi, so if you have a laptop around it's much quicker to run the three scripts there and copy the finished avian/assets/illustrations/ over. once build_masks.py has run, reload the page and the new birds will show up.

and on sharing illustrations, this would be wonderful!! the fastest path in my mind is drop your illustrations in a fork and share the link here in the comments so anyone in your region can use it! A couple of folks have already gone this way. I've been spending a bit of free time building out a much larger illustration bundle covering all of North America as a long term solution here. I'm admittedly a bit zapped on the reviewing plumage front, but will be spending more time on this in the future!

[jochter67]

Thank you for your answers.
I generates 142 Pictures, it cost me 4,22€.
I used the script make_region_labels.py from arturo bruzini to generate a labels.txt for my part of the world. He has a fork on Github.
It worked great.
One note about requirements.txt. If i do a pip install -r requirements.txt on the RPi i get an error message that the enviroment is externally managed.
So i created a virtual envirement with python3 -m venv .venv in the /scripts folder.
I entered the venv with source .venv/bin/activate. After that the pip install -r requirements.txt worked.
I will share my drawings on github once everything is finished.

[jochter67]

Hi,
i finally got everything to work.
cutout.py was killed by linux on my Raspi5 8GB because it consumed all the RAM.
So i started to run cutout on my 'big' computer (8 Core AMD, 16GB no GPU).
Same Problem here, the Computer crashed.
Then i added these Enviroment Variables:
export OMP_NUM_THREADS=1
export OPENBLAS_NUM_THREADS=1
export MKL_NUM_THREADS=1
export NUMEXPR_NUM_THREADS=1
after that the cutout.py ran successfully.
It seems that cutout.py or better rembg or even better onnxruntime is pretty RAM hungry and takes everything it gets.
These Variables instruct ONNXruntime to be not so hungry.
There is also a dedicated rembg only for CPU usage.
You can install it with:
pip install "rembg[cpu]"

You can find my illustrations on github
https://github.com/jochter67/AvianVisitors

Thanks a lot for this wonderful project.

[emt-eng]

This is soo cool! I'm curious how plug and play this actually is if I purchased the bundles you posted and tried to set it up. I'm pretty savvy, just not in the coding world so don't want to bite off something too big, but really want this at my house!

[entername-here]

I found 95% of it was pretty much plug 'n play. I already had everything but the mic, so I ordered what was linked, then followed the directions. I ran into a small issue getting the fancy front end to behave (you can see it noted above), but it sounds like that was fixed in subsequent patches.

The only piece that I've had less luck on are generating bird images for my area. This, too, sounds like something that's being worked on, so I expect it will get better and easier as time and updates go. If you're excited about it and willing to do some futzing if anything misbehaves, I'd say go for it. It's been really need to see it working at my house. :)

[cdkl]

This idea is fantastic and I'm intending to reproduce the eink display, but in the meantime I needed to adapt it to my birdnet-go setup. (Love birdnet-pi, made some contributions to it, have 4 years of data for it but birdnet-go is just a better package overall and had a rest API.)

I put together this package designed to run as a separate service alongside birdnet-go. Early stages but you can find it here: https://github.com/cdkl/birdnet-collage

Running example, still lacking eastern NA birds, here: http://birdcollage.cdklein.com

[philipgraham74-pixel]

Hi. Just seen this article posted on a UK Birding Discord server. I've built my own parabolic mic (USB-C) mainly for NocMig, best result being a recording of a very rare (for my area) quail at 0212 in the morning.
I was wondering how or if it's possible to run this to detect UK species, and can it display on anything other than an E ink display?