diff --git a/.github/labeler.yml b/.github/labeler.yml index 2a2383ec..546de4bf 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -1,4 +1,4 @@ -documentation: readme.md +documentation: readme.mustache images: plane_images.csv ukraine: plane-alert-ukraine.csv twitter: plane-alert-twitter.csv diff --git a/.github/workflows/update_readme.yml b/.github/workflows/update_readme.yml new file mode 100644 index 00000000..b9a25c51 --- /dev/null +++ b/.github/workflows/update_readme.yml @@ -0,0 +1,35 @@ +name: Update README.md for Changes + +permissions: + contents: write # Allow action to write back changes to repository. + +on: + push: + branches: ["main"] + paths: + - "plane-alert-db.csv" + - "plane-alert-ukraine.csv" + - "plane-alert-pia.csv" + - "plane_images.csv" + - "scripts/update_readme.py" + +jobs: + updateREADME.md: + if: github.repository == 'sdr-enthusiasts/plane-alert-db' || ${{ vars.CREATE_DERIVATIVES }} + name: Update README.md documentation for Changes + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v4 + with: + python-version: "3.10" + cache: "pip" + - run: pip install -r ./scripts/requirements.txt + + - name: Update README.md for changes in the database files + run: python ./scripts/update_readme.py + + - name: Commit README.md + uses: stefanzweifel/git-auto-commit-action@v5 + with: + commit_message: "refactor: update README.md documentation." diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 21eb5761..4bf18bf0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -28,13 +28,30 @@ Pull requests are the best way to propose changes to the codebase (we use [Githu 8. Issue that pull request! 9. Merge your feature branch into your own `main` branch, so you don't have to wait for the PR to be merged. +## Important Development Notes + +### Database Updates + +Refer to the [README](README.md) for details on contributing to the following main databases: + +- [plane-alert-db.csv](plane-alert-db.csv) +- [plane-alert-pia.csv](plane-alert-pia.csv) +- [plane-alert-ukraine.csv](plane-alert-ukraine.csv) +- [plane_images.csv](plane_images.csv) + +Please note that other databases are automatically generated via [GitHub Actions](https://github.com/sdr-enthusiasts/plane-alert-db/actions/workflows/create_db_derivatives.yaml) and should not be manually edited. + +### Readme Update + +The readme is dynamically generated through the [update_readme.yml](https://github.com/sdr-enthusiasts/plane-alert-db/actions/workflows/update_readme.yml) action using the mustache template language and the chevron parser. For any modifications, exclusively edit the [readme.mustache](readme.mustache) file. + ## Keep your fork up to date You can keep your fork, and thus your private Vercel instance up to date with the upstream using GitHubs' [Sync Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork) button. You can also use the [pull](https://github.com/wei/pull) package created by [@wei](https://github.com/wei) to automate this process. ## Automatically create the derivative databases -As the [README](README.md) explains, this repository uses GitHub actions to create several derivative databases from the main databases. By default, to prevent conflicts, the [create_db_derivatives.yaml](.github/workflows/create_db_derivatives.yaml) action is disabled on forks. You can, however, set the `CREATE_DERIVATIVES` repository variable to `true` in your repository settings (see [the GitHub documentation](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository)) if you want to create the derivative database on your fork automatically. +As the [README](README.md) explains, this repository uses GitHub actions to create several derivative databases from the main databases. By default, to prevent conflicts, the [create_db_derivatives.yaml](.github/workflows/create_db_derivatives.yaml) action is disabled on forks. You can, however, set the `CREATE_DERIVATIVES` repository variable to `true` in your repository settings (see [the GitHub documentation](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository)) if you want to create the derivative database on your fork automatically. > **Warning** > If you enable the building of the derivative databases on your fork, please use a feature branch (e.g. `patch`) when creating pull requests to the main repository. This will prevent your PR from being flagged as `invalid` since commits made by the [create_db_derivatives.yaml](.github/workflows/create_db_derivatives.yaml) do not re-trigger the PR check actions. You can then merge your changes into your main branch without waiting for the PR to be merged. diff --git a/README.md b/README.md index 90705bd1..45b96002 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,14 @@ + + # plane-alert-db -This project consists of lists of 'interesting' aircraft, formatted as CSV files. The list is designed to work with the excellent ****. +This project consists of lists of 'interesting' aircraft, formatted as CSV files. The list is designed to work with the excellent ****. > **Warning** > Please only suggest/make any changes to the [plane-alert-db.csv](plane-alert-db.csv), [plane-alert-pia.csv](plane-alert-pia.csv), [plane-alert-ukraine.csv](plane-alert-ukraine.csv) and [plane_images.csv](plane_images.csv) files on GitHub - all other files (except PIA) are generated from this file, and if you do not make your changes there, they will be overwritten and lost. Additionally, it is **not recommended** to edit the CSV files in Microsoft Excel, as Excel will attempt to "fix" some ICAO hexes and other fields. It's better to use a code editor such as VS Studio Code—you can access the web version of Code by pressing the period key . when viewing the file you wish to edit. @@ -16,20 +24,20 @@ This project consists of lists of 'interesting' aircraft, formatted as CSV files ## Current Content -There currently are about **13340** unique aircraft in **55** categories found in this repository. This [Dashboard](https://lookerstudio.google.com/reporting/46ff4328-09d3-4e65-ab5a-bd2ba27a18fd/page/4taCC) contains details of the main list and the most recent additions. +There currently are about **13491** unique aircraft in **53** categories found in this repository. This [Dashboard](https://lookerstudio.google.com/reporting/46ff4328-09d3-4e65-ab5a-bd2ba27a18fd/page/4taCC) contains details of the main list and the most recent additions. These aircraft are divided into four main databases: -- [plane-alert-db.csv](plane-alert-db.csv) - A list of interesting aircraft with tags, categories and links. (13242) -- [plane-alert-pia.csv](plane-alert-pia.csv): A list that contains PIA planes. (55) +- [plane-alert-db.csv](plane-alert-db.csv) - A list of interesting aircraft with tags, categories and links. (13459) +- [plane-alert-pia.csv](plane-alert-pia.csv): A list that contains PIA planes. (57) - [plane-alert-ukraine.csv](plane-alert-ukraine.csv): A list with Ukrainian planes. (32) -- [plane_images.csv](plane_images.csv): A accompanying list that contains aircraft images. (10557) +- [plane_images.csv](plane_images.csv): A accompanying list that contains aircraft images. (10844) Based on these main databases, several derivative databases are created using a [GitHub action](https://github.com/sdr-enthusiasts/plane-alert-db/actions/workflows/create_db_derivatives.yaml): -- [plane-alert-civ.csv](plane-alert-civ.csv) - Civilian Registered Aircraft, includes Historic and Distinctive. (3310) -- [plane-alert-mil.csv](plane-alert-mil.csv) - Military Only. (7065) -- [plane-alert-pol.csv](plane-alert-pol.csv) - Police Forces. (862) -- [plane-alert-gov.csv](plane-alert-gov.csv) - Governments, Gov Agencies and Dictators. (1590) +- [plane-alert-civ.csv](plane-alert-civ.csv) - Civilian Registered Aircraft, includes Historic and Distinctive. (3599) +- [plane-alert-mil.csv](plane-alert-mil.csv) - Military Only. (7339) +- [plane-alert-pol.csv](plane-alert-pol.csv) - Police Forces. (902) +- [plane-alert-gov.csv](plane-alert-gov.csv) - Governments, Gov Agencies and Dictators. (1619) A second version of each of the above lists contains up to 4 image links per aircraft. These lists are created in [GitHub action](https://github.com/sdr-enthusiasts/plane-alert-db/actions/workflows/create_db_derivatives.yaml) using the [plane_images.csv](plane_images.csv) database. **Please consider this experimental, do not come to rely on any of the image links** @@ -40,7 +48,7 @@ A second version of each of the above lists contains up to 4 image links per air - [plane-alert-pol-images.csv](plane-alert-pol-images.csv) - [plane-alert-gov-images.csv](plane-alert-gov-images.csv) -Note, we used to create a seperate list, `plane-alert-twitter-blocked.csv`, for use with Planefence's Twitter posting functionality. This list would prevent certain aircraft from being posted to Twitter in an attempt to keep the posting bot account from being banned. Since Twitter has now made it all but impossible for users to make bots for free, we've stopped creating this list. +Note, we used to create a seperate list, `plane-alert-twitter-blocked.csv`, for use with Planefence's Twitter posting functionality. This list would prevent certain aircraft from being posted to Twitter in an attempt to keep the posting bot account from being banned. Since Twitter has now made it all but impossible for users to make bots for free, we've stopped creating this list. This [Dashboard](https://lookerstudio.google.com/reporting/46ff4328-09d3-4e65-ab5a-bd2ba27a18fd) contains details of the [main](https://github.com/sdr-enthusiasts/plane-alert-db/blob/main/plane-alert-db.csv) and [Ukraine](https://github.com/sdr-enthusiasts/plane-alert-db/blob/main/plane-alert-ukraine.csv) lists. @@ -48,51 +56,51 @@ This [Dashboard](https://lookerstudio.google.com/reporting/46ff4328-09d3-4e65-ab Think of categories like groups, with similar or related aircraft listed together. This allows you to easily select a subset of the list for your own use. The category names (and tags) come from my rather idiosyncratic sense of humour. If you have better suggestions I'm all ears. -- Aerobatic Teams - Red Arrows, Blue Angels etc. (65) +- Aerobatic Teams - Red Arrows, Blue Angels etc. (77) - Army Air Corp - UK Army Air Corp. Mainly Helicopters (94) -- As Seen on TV - Companies and Brands (368) +- As Seen on TV - Companies and Brands (367) - Big Hello - Large Helicopters (sic) (104) -- Bizjets - Fancy pants planes for fancy pants people (38) -- Climate Crisis - Oil Companies, Large Business Jets - BBJs and ACJs (169) -- Coastguard - Coastguard, Customs and Border Patrols (434) +- Bizjets - Fancy pants planes for fancy pants people (39) +- Climate Crisis - Oil Companies, Large Business Jets - BBJs and ACJs (186) +- Coastguard - Coastguard, Customs and Border Patrols (438) - Da Comrade - Russian or Soviet Aircraft. I love their design, so they get their own category (91) -- Dictator Alert - People of potentially questionable morals and values (322) -- Distinctive - Unique and/or special aircraft e.g. The AN-225 Myria, NASA aircraft, Testbeds (178) -- Dogs with Jobs - Aircraft with specific roles and/or modifications (163) -- Don't you know who I am? - Famous People. I was going to say notable, but I'll go with Famous (21) -- Flying Doctors - Air Ambulance and Medical Flights (658) -- Football - Actual, Aussie Rules or American. We don't discriminate. (2) -- GAF - Aircraft of the German Air Force, thank to Rhodan76 (401) +- Dictator Alert - People of potentially questionable morals and values (323) +- Distinctive - Unique and/or special aircraft e.g. The AN-225 Myria, NASA aircraft, Testbeds (182) +- Dogs with Jobs - Aircraft with specific roles and/or modifications (170) +- Don't you know who I am? - Famous People. I was going to say notable, but I'll go with Famous (59) +- Flying Doctors - Air Ambulance and Medical Flights (726) +- Football - Actual, Aussie Rules or American. We don't discriminate. (6) +- GAF - Aircraft of the German Air Force, thank to Rhodan76 (402) - Gas Bags - Would you like to ride in my beautiful balloon? (14) -- Governments - Aircraft registered to Governments (237) -- Gunship - Brrrrrrrrrrrrrrrrrrrt (256) -- Hired Gun - Why do the dirty work when someone else can do it for you? (135) -- Historic - It's older than I am and most likely has a prop. (355) +- Governments - Aircraft registered to Governments (243) +- Gunship - Brrrrrrrrrrrrrrrrrrrt (257) +- Hired Gun - Why do the dirty work when someone else can do it for you? (195) +- Historic - It's older than I am and most likely has a prop. (394) - Jesus he Knows me - Aircraft owned and operated by Religious organisations (20) -- Joe Cool - Cool Planes. Or at least I think they are cool. (197) +- Joe Cool - Cool Planes. Or at least I think they are cool. (195) - Jump Johnny Jump - de Havilland Chipmunks. Air Cadets of a certain age will understand. (388) - Nuclear - Nuclear Emergency Support Team etc. (16) - Oligarch - I made this money all by myself. (41) -- Other Air Forces - Air Force aircraft that are not RAF or USAF (1991) -- Other Navies - Navy Aircraft that are not Royal Navy Fleet Air Arm or United States Navy (188) -- Oxcart - Intelligence gathering aircraft (687) +- Other Air Forces - Air Force aircraft that are not RAF or USAF (1974) +- Other Navies - Navy Aircraft that are not Royal Navy Fleet Air Arm or United States Navy (189) +- Oxcart - Intelligence gathering aircraft (736) - Perfectly Serviceable Aircraft - Why do you keep jumping out of a Perfectly Serviceable Aircraft aka Skydiving planes (43) - PIA - Privacy ICAO Address....you can run, but you cannot hide (16) -- Police Forces - Your friendly neighbourhood flying (insert local colloquialism here) (845) -- Ptolemy would be proud - Mapping and Aerial Survey aircraft. (110) +- Police Forces - Your friendly neighbourhood flying (insert local colloquialism here) (885) +- Ptolemy would be proud - Mapping and Aerial Survey aircraft. (111) - Quango - Nato, United Nations, World Bank etc. (32) - Radiohead - Very Very special aircraft. Think VC25. (6) -- RAF - Aircraft of the Royal Air Force (229) +- RAF - Aircraft of the Royal Air Force (231) - Royal Aircraft - Aircraft used or owned by the UK Royal Family (8) - Royal Navy Fleet Air Arm - Aircraft of the Royal Navy Fleet Air Arm (97) -- Sam Tân - Firefighting Aircraft. (301) -- Special Forces - The best of the best of the best. Sir. (161) -- Toy Soldiers - Armies from around the world (553) -- UAV - It's not natural, I tell 'ya (21) +- Sam Tân - Firefighting Aircraft. (326) +- Special Forces - The best of the best of the best. Sir. (163) +- Toy Soldiers - Armies from around the world (621) +- UAV - It's not natural, I tell 'ya (30) - UK National Police Air Service - Your friendly neighbourhood flying bobby (24) -- United States Navy - United States naval avaitors. Some say they are the best of the best. (243) -- USAF - Aircraft of the United States Air Force (2138) -- Vanity Plate - Distinctive registrations (66) +- United States Navy - United States naval avaitors. Some say they are the best of the best. (168) +- USAF - Aircraft of the United States Air Force (2183) +- Vanity Plate - Distinctive registrations (78) - Watch Me Fly - Flying and Training Schools (75) - You came here in that thing? - Microlights, tiny planes and helis..think Yakima Super Breezy (thanks skstrand). (98) - Zoomies - Fast jets, fighters. Anything that moves fast. (134) diff --git a/plane-alert-db.csv b/plane-alert-db.csv index d5dc2e86..81cba00d 100755 --- a/plane-alert-db.csv +++ b/plane-alert-db.csv @@ -2727,7 +2727,7 @@ A00E20,N102WK,Willis Knighton Medical Center,F90 King Air,BE9L,Civ,Air Ambo,Medi 406CBC,G-WLTS,Wiltshire Air Ambulance,Bell 429 GlobalRanger,B429,Civ,Air Ambo,Medical Evac,Saving Lives,Flying Doctors,https://www.wiltshireairambulance.co.uk 407045,G-YOAA,Yorkshire Air Ambulance,Eurocopter EC145,EC45,Civ,Air Ambo,Medical Evac,Saving Lives,Flying Doctors,https://www.yorkshireairambulance.org.uk 407046,G-YAAC,Yorkshire Air Ambulance,MBB-Kawasaki BK 117 D-2,BK17,Civ,Air Ambo,Medical Evac,Saving Lives,Flying Doctors,https://www.yorkshireairambulance.org.uk/ -43EA62,M-LCFC,Leicester City Football Club,Boeing 737-BBJ,B737,Civ,Jumpers For Goalposts,Boeing Business Jet,LCFC,Football ,https://www.lcfc.com +43EA62,M-LCFC,Leicester City Football Club,Boeing 737-BBJ,B737,Civ,Jumpers For Goalposts,Boeing Business Jet,LCFC,Football,https://www.lcfc.com 48434F,P4-MES,Roman Abramovitch,Boeing 767-ER,B763,Civ,Jumpers For Goalposts,The Bandit,Chelsea,Football ,https://youtu.be/jAG4XXCOj48 43C33B,ZJ700,BAE Systems,Eurofighter Typhoon,EUFI,Mil,Delta Wing,Danger Zone,Luftwaffe,GAF,https://www.bundeswehr.de/de/organisation/luftwaffe 3F851B,10+27,German Air Force,Airbus A310-304,A310,Mil,Not a Bus,Troop Transport,Luftwaffe,GAF,https://www.bundeswehr.de/de/organisation/luftwaffe @@ -13139,14 +13139,14 @@ A6A904,N5280F,Houston Police Department,MD Helicopters 369 E,H500,Pol,Police Squ A6A990,N5284F,Houston Police Department,MD Helicopters 369 E,H500,Pol,Police Squad,The Cops,Copper Chopper,Police Forces,https://www.houstontx.gov/police/divisions/air_support/index.htm AB74FF,N8372F,Houston Police Department,MD Helicopters 369 E,H500,Pol,Police Squad,The Cops,Copper Chopper,Police Forces,https://www.houstontx.gov/police/divisions/air_support/index.htm ABF8B4,N8700F,Houston Police Department,Schweizer 269 C,H269,Pol,Police Squad,The Cops,Copper Chopper,Police Forces,https://www.houstontx.gov/police/divisions/air_support/index.htm -AB4176,N824TX,Texas Department of Public Safety,Eurocopter Squirrel AS.350 B3,AS50,Pol,Police Squad,The Cops,Copper Chopper,Police Force,https://www.dps.texas.gov/section/aircraft-operations-division -AC6E92,N90TX,Texas Department of Public Safety,Eurocopter Squirrel AS.350 B2,AS50,Pol,Police Squad,The Cops,Copper Chopper,Police Force,https://www.dps.texas.gov/section/aircraft-operations-division -A4C0F3,N405TX,Texas Department of Public Safety,Eurocopter Squirrel AS.350 B2,AS50,Pol,Police Squad,The Cops,Copper Chopper,Police Force,https://www.dps.texas.gov/section/aircraft-operations-division -A7C6A5,N60TX,Texas Department of Public Safety,Eurocopter Squirrel AS.350 B2,AS50,Pol,Police Squad,The Cops,Copper Chopper,Police Force,https://www.dps.texas.gov/section/aircraft-operations-division -A16DA1,N191TX,Texas Department of Public Safety,Eurocopter Squirrel AS.350 B3,AS50,Pol,Police Squad,The Cops,Copper Chopper,Police Force,https://www.dps.texas.gov/section/aircraft-operations-division -AB9074,N844TX,Texas Department of Public Safety,Eurocopter Squirrel AS.350 B3,AS50,Pol,Police Squad,The Cops,Copper Chopper,Police Force,https://www.dps.texas.gov/section/aircraft-operations-division -A1A29E,N204TX,Texas Department of Public Safety,Eurocopter Squirrel AS.350 B3,AS50,Pol,Police Squad,The Cops,Copper Chopper,Police Force,https://www.dps.texas.gov/section/aircraft-operations-division -AC9BE9,N911RR,Monroe County Sheriffs Office,Sikorsky S-76C,S76,Pol,Police Squad,The Cops,Copper Chopper,Police Force,https://www.keysso.net/ +AB4176,N824TX,Texas Department of Public Safety,Eurocopter Squirrel AS.350 B3,AS50,Pol,Police Squad,The Cops,Copper Chopper,Police Forces,https://www.dps.texas.gov/section/aircraft-operations-division +AC6E92,N90TX,Texas Department of Public Safety,Eurocopter Squirrel AS.350 B2,AS50,Pol,Police Squad,The Cops,Copper Chopper,Police Forces,https://www.dps.texas.gov/section/aircraft-operations-division +A4C0F3,N405TX,Texas Department of Public Safety,Eurocopter Squirrel AS.350 B2,AS50,Pol,Police Squad,The Cops,Copper Chopper,Police Forces,https://www.dps.texas.gov/section/aircraft-operations-division +A7C6A5,N60TX,Texas Department of Public Safety,Eurocopter Squirrel AS.350 B2,AS50,Pol,Police Squad,The Cops,Copper Chopper,Police Forces,https://www.dps.texas.gov/section/aircraft-operations-division +A16DA1,N191TX,Texas Department of Public Safety,Eurocopter Squirrel AS.350 B3,AS50,Pol,Police Squad,The Cops,Copper Chopper,Police Forces,https://www.dps.texas.gov/section/aircraft-operations-division +AB9074,N844TX,Texas Department of Public Safety,Eurocopter Squirrel AS.350 B3,AS50,Pol,Police Squad,The Cops,Copper Chopper,Police Forces,https://www.dps.texas.gov/section/aircraft-operations-division +A1A29E,N204TX,Texas Department of Public Safety,Eurocopter Squirrel AS.350 B3,AS50,Pol,Police Squad,The Cops,Copper Chopper,Police Forces,https://www.dps.texas.gov/section/aircraft-operations-division +AC9BE9,N911RR,Monroe County Sheriffs Office,Sikorsky S-76C,S76,Pol,Police Squad,The Cops,Copper Chopper,Police Forces,https://www.keysso.net/ A4EE26,N417AE,Air Evac Lifeteam,Bell Jet Ranger,B06,Civ,Air Ambo,Medical Evac,Saving Lives,Flying Doctors,https://lifeteam.net/home A03760,N113AH,TVPX Aircraft Solutions Inc Trustee,Eurocopter MBB-BK 117 C-2 (EC145),EC45,Civ,Air Ambo,Medical Evac,Saving Lives,Flying Doctors,https://www.helis.com/database/cn/55367/ A278F9,N259AM,Air Methods Corp,Eurocopter EC-130 B4,EC30,Civ,Air Ambo,Medical Evac,Saving Lives,Flying Doctors,https://www.airmethods.com/ diff --git a/readme.mustache b/readme.mustache new file mode 100644 index 00000000..93416a29 --- /dev/null +++ b/readme.mustache @@ -0,0 +1,166 @@ + + +# plane-alert-db + +This project consists of lists of 'interesting' aircraft, formatted as CSV files. The list is designed to work with the excellent ****. + +> **Warning** +> Please only suggest/make any changes to the [plane-alert-db.csv](plane-alert-db.csv), [plane-alert-pia.csv](plane-alert-pia.csv), [plane-alert-ukraine.csv](plane-alert-ukraine.csv) and [plane_images.csv](plane_images.csv) files on GitHub - all other files (except PIA) are generated from this file, and if you do not make your changes there, they will be overwritten and lost. Additionally, it is **not recommended** to edit the CSV files in Microsoft Excel, as Excel will attempt to "fix" some ICAO hexes and other fields. It's better to use a code editor such as VS Studio Code—you can access the web version of Code by pressing the period key . when viewing the file you wish to edit. + +## TOC + +- [Current Content](#current-content) +- [Description of Categories](#description-of-categories) +- [Planefence](#planefence) +- [Contributing](#contributing) +- [Disclaimer, excuses and dodges](#disclaimer-excuses-and-dodges) +- [Data Sources](#data-sources) + +## Current Content + +There currently are about **{{planes}}** unique aircraft in **{{categories}}** categories found in this repository. This [Dashboard](https://lookerstudio.google.com/reporting/46ff4328-09d3-4e65-ab5a-bd2ba27a18fd/page/4taCC) contains details of the main list and the most recent additions. +These aircraft are divided into four main databases: + +- [plane-alert-db.csv](plane-alert-db.csv) - A list of interesting aircraft with tags, categories and links. ({{plane_alert_db}}) +- [plane-alert-pia.csv](plane-alert-pia.csv): A list that contains PIA planes. ({{plane_alert_pia}}) +- [plane-alert-ukraine.csv](plane-alert-ukraine.csv): A list with Ukrainian planes. ({{plane_alert_ukraine}}) +- [plane_images.csv](plane_images.csv): A accompanying list that contains aircraft images. ({{plane_alert_images}}) + +Based on these main databases, several derivative databases are created using a [GitHub action](https://github.com/sdr-enthusiasts/plane-alert-db/actions/workflows/create_db_derivatives.yaml): + +- [plane-alert-civ.csv](plane-alert-civ.csv) - Civilian Registered Aircraft, includes Historic and Distinctive. ({{civ_count}}) +- [plane-alert-mil.csv](plane-alert-mil.csv) - Military Only. ({{mil_count}}) +- [plane-alert-pol.csv](plane-alert-pol.csv) - Police Forces. ({{pol_count}}) +- [plane-alert-gov.csv](plane-alert-gov.csv) - Governments, Gov Agencies and Dictators. ({{gov_count}}) + +A second version of each of the above lists contains up to 4 image links per aircraft. These lists are created in [GitHub action](https://github.com/sdr-enthusiasts/plane-alert-db/actions/workflows/create_db_derivatives.yaml) using the [plane_images.csv](plane_images.csv) database. **Please consider this experimental, do not come to rely on any of the image links** + +- [plane-alert-db-images.csv](plane-alert-db-images.csv) +- [plane-alert-ukraine-images.csv](plane-alert-ukraine.csv) +- [plane-alert-civ-images.csv](plane-alert-civ-images.csv) +- [plane-alert-mil-images.csv](plane-alert-mil-images.csv) +- [plane-alert-pol-images.csv](plane-alert-pol-images.csv) +- [plane-alert-gov-images.csv](plane-alert-gov-images.csv) + +Note, we used to create a seperate list, `plane-alert-twitter-blocked.csv`, for use with Planefence's Twitter posting functionality. This list would prevent certain aircraft from being posted to Twitter in an attempt to keep the posting bot account from being banned. Since Twitter has now made it all but impossible for users to make bots for free, we've stopped creating this list. + +This [Dashboard](https://lookerstudio.google.com/reporting/46ff4328-09d3-4e65-ab5a-bd2ba27a18fd) contains details of the [main](https://github.com/sdr-enthusiasts/plane-alert-db/blob/main/plane-alert-db.csv) and [Ukraine](https://github.com/sdr-enthusiasts/plane-alert-db/blob/main/plane-alert-ukraine.csv) lists. + +## Description of Categories + +Think of categories like groups, with similar or related aircraft listed together. This allows you to easily select a subset of the list for your own use. The category names (and tags) come from my rather idiosyncratic sense of humour. If you have better suggestions I'm all ears. + +- Aerobatic Teams - Red Arrows, Blue Angels etc. ({{aerobatic_count}}) +- Army Air Corp - UK Army Air Corp. Mainly Helicopters ({{air_corp_count}}) +- As Seen on TV - Companies and Brands ({{seen_on_tv_count}}) +- Big Hello - Large Helicopters (sic) ({{big_hello_count}}) +- Bizjets - Fancy pants planes for fancy pants people ({{bizjets_count}}) +- Climate Crisis - Oil Companies, Large Business Jets - BBJs and ACJs ({{climate_crisis_count}}) +- Coastguard - Coastguard, Customs and Border Patrols ({{coastguard_count}}) +- Da Comrade - Russian or Soviet Aircraft. I love their design, so they get their own category ({{da_comrade_count}}) +- Dictator Alert - People of potentially questionable morals and values ({{dictator_count}}) +- Distinctive - Unique and/or special aircraft e.g. The AN-225 Myria, NASA aircraft, Testbeds ({{distinctive_count}}) +- Dogs with Jobs - Aircraft with specific roles and/or modifications ({{dogs_jobs_count}}) +- Don't you know who I am? - Famous People. I was going to say notable, but I'll go with Famous ({{celeb_count}}) +- Flying Doctors - Air Ambulance and Medical Flights ({{flying_doctors_count}}) +- Football - Actual, Aussie Rules or American. We don't discriminate. ({{football_count}}) +- GAF - Aircraft of the German Air Force, thank to Rhodan76 ({{gaf_count}}) +- Gas Bags - Would you like to ride in my beautiful balloon? ({{gas_bags_count}}) +- Governments - Aircraft registered to Governments ({{governments_count}}) +- Gunship - Brrrrrrrrrrrrrrrrrrrt ({{gunship_count}}) +- Hired Gun - Why do the dirty work when someone else can do it for you? ({{hired_gun_count}}) +- Historic - It's older than I am and most likely has a prop. ({{historic_count}}) +- Jesus he Knows me - Aircraft owned and operated by Religious organisations ({{religious_count}}) +- Joe Cool - Cool Planes. Or at least I think they are cool. ({{joe_cool_count}}) +- Jump Johnny Jump - de Havilland Chipmunks. Air Cadets of a certain age will understand. ({{jump_johnny_count}}) +- Nuclear - Nuclear Emergency Support Team etc. ({{nuclear_count}}) +- Oligarch - I made this money all by myself. ({{oligarch_count}}) +- Other Air Forces - Air Force aircraft that are not RAF or USAF ({{other_air_count}}) +- Other Navies - Navy Aircraft that are not Royal Navy Fleet Air Arm or United States Navy ({{other_navies_count}}) +- Oxcart - Intelligence gathering aircraft ({{oxcart_count}}) +- Perfectly Serviceable Aircraft - Why do you keep jumping out of a Perfectly Serviceable Aircraft aka Skydiving planes ({{psa_count}}) +- PIA - Privacy ICAO Address....you can run, but you cannot hide ({{pia_count}}) +- Police Forces - Your friendly neighbourhood flying (insert local colloquialism here) ({{police_forces_count}}) +- Ptolemy would be proud - Mapping and Aerial Survey aircraft. ({{ptolemy_count}}) +- Quango - Nato, United Nations, World Bank etc. ({{quango_count}}) +- Radiohead - Very Very special aircraft. Think VC25. ({{radiohead_count}}) +- RAF - Aircraft of the Royal Air Force ({{raf_count}}) +- Royal Aircraft - Aircraft used or owned by the UK Royal Family ({{royal_aircraft_count}}) +- Royal Navy Fleet Air Arm - Aircraft of the Royal Navy Fleet Air Arm ({{royal_navy_count}}) +- Sam Tân - Firefighting Aircraft. ({{aerial_firefighter_count}}) +- Special Forces - The best of the best of the best. Sir. ({{special_forces_count}}) +- Toy Soldiers - Armies from around the world ({{toy_soldiers_count}}) +- UAV - It's not natural, I tell 'ya ({{uav_count}}) +- UK National Police Air Service - Your friendly neighbourhood flying bobby ({{uk_police_count}}) +- United States Navy - United States naval avaitors. Some say they are the best of the best. ({{us_navy_count}}) +- USAF - Aircraft of the United States Air Force ({{usaf_count}}) +- Vanity Plate - Distinctive registrations ({{vanity_plate_count}}) +- Watch Me Fly - Flying and Training Schools ({{watch_fly_count}}) +- You came here in that thing? - Microlights, tiny planes and helis..think Yakima Super Breezy (thanks skstrand). ({{that_thing_count}}) +- Zoomies - Fast jets, fighters. Anything that moves fast. ({{zoomies_count}}) + +## Planefence + +The list takes the form: + +| $ICAO | $Registration | $Operator | $Type | $ICAO Type | #CMPG | $Tag 1 | $#Tag 2 | $#Tag 3 | Category | $#Link | +| ------ | ------------- | ------------------------ | -------------------- | ---------- | ----- | ---------------- | ------------ | ---------- | --------------- | ---------------------------------------------------- | +| 502C5C | YL-KSH | Baltic Bees display team | Aero L-39C Albatross | L39 | Civ | Do A Barrel Roll | Display Team | Aerobatics | Aerobatic Teams | | + +To use this list with Planefence, configure your `planefence.config` setup to include the following line: + +```config +PF_ALERTLIST=https://raw.githubusercontent.com/sdr-enthusiasts/plane-alert-db/main/plane-alert-db.csv +``` + +If you want to add the list in addition to your local plane-alert-db.csv list, you can do the following: + +```config +PF_ALERTLIST=plane-alert-db.csv,https://raw.githubusercontent.com/sdr-enthusiasts/plane-alert-db/main/plane-alert-gov.csv,https://raw.githubusercontent.com/sdr-enthusiasts/plane-alert-db/main/plane-alert-pol.csv +``` + +> **Note** +> The priority of use is first-to-last, so if you want your local list to be interpreted first, move it to the front of the list. + +Add these characters to the column headers to control the behaviour of PlaneAlert + +- `$` - Tweet this column as #hashtag. +- `#` - Don't show on the website (it will ignore this for the ICAO field, which is always shown). +- `$#` - Don't show on the website; tweet as a #hashtag. + +## Contributing + +Feel free to [open an issue](https://github.com/sdr-enthusiasts/plane-alert-db/issues) if you have ideas on improving this repository or want to report a bug! All contributions are welcome 🚀. Please consult the [contribution guidelines](CONTRIBUTING.md) for more information. You can also check out the [TODOS](TODOS.md) page if you want to contribute to this repository but need some ideas. + +> **Warning** +> As also [explained above](#current-content), this repository contains four main databases to which people can contribute. The other databases are created automatically using [GitHub action](https://github.com/sdr-enthusiasts/plane-alert-db/actions/workflows/create_db_derivatives.yaml). As a result, please only suggest/make any changes to these main databases. Changes made to all other CSV files will be overwritten and lost. Additionally, it is **not recommended** to edit the CSV files in Microsoft Excel, as Excel will attempt to "fix" some ICAO hexes and other fields. It's better to use a code editor such as VS Studio Code—you can access the web version of Code by pressing the period key . when viewing the file you wish to edit. + +If you're creating a pull request with additions, please add them to the end of the file. We may sort the list periodically to group like planes together. + +## Disclaimer, excuses and dodges + +This is not intended to be a definitive list, especially when it comes to aircraft models. Where the same model of aircraft is made by several manufacturers I won't always have the correct one. If you thought it was a Beechcraft King Air 200 and actually it was a Textron Super King Air B200GT, I won't be losing any sleep. There are other data sources (see below) if you want absolute accuracy. + +## Data Sources + +This data has been gathered from far too many sources to mention, but some sites have been _really_ useful: + +- +- +- +- +- +- +- +- +- +- +- +- +- diff --git a/scripts/requirements.txt b/scripts/requirements.txt index 5db01be2..204f570c 100644 --- a/scripts/requirements.txt +++ b/scripts/requirements.txt @@ -2,3 +2,4 @@ pandas numpy requests gitpython +chevron diff --git a/scripts/update_readme.py b/scripts/update_readme.py new file mode 100644 index 00000000..eabf4f2b --- /dev/null +++ b/scripts/update_readme.py @@ -0,0 +1,114 @@ +"""Script that performs several counts to update the README +""" + +import logging +import sys + +import pandas as pd + +logging.basicConfig( + format="%(asctime)s %(levelname)-8s [%(name)s] %(message)s", level=logging.INFO +) + +if __name__ == "__main__": + logging.info("Reading the main csv file...") + df = pd.read_csv("plane-alert-db.csv") + logging.info("Main csv file read successfully.") + + logging.info("Reading the Ukraine csv file...") + ukraine_df = pd.read_csv("plane-alert-ukraine.csv") + + logging.info("Reading the PIA csv file...") + pia_df = pd.read_csv("plane-alert-pia.csv") + + logging.info("Reading the images reference file...") + images_df = pd.read_csv("plane_images.csv") + + plane_count_df = ( + pd.concat([df["$ICAO"], ukraine_df["$ICAO"]]) + .drop_duplicates() + .reset_index(drop=True) + ) + + category_unique_df = ( + pd.concat([df["Category"], ukraine_df["Category"]]) + .drop_duplicates() + .reset_index(drop=True) + ) + + category_df = ( + pd.concat([df["Category"], ukraine_df["Category"]]) + .reset_index(drop=False) + ) + +import chevron + +with open('readme.mustache', 'r') as template: + with open('README.md', 'w') as output: + output.write(chevron.render(template, + { + 'planes': plane_count_df.shape[0], + 'categories': category_unique_df.shape[0], + 'plane_alert_db': df.shape[0], + 'plane_alert_pia': pia_df.shape[0], + 'plane_alert_ukraine': ukraine_df.shape[0], + 'plane_alert_images': images_df.dropna(subset=['#ImageLink'],inplace=False).shape[0], + 'civ_count': df[df["#CMPG"] == 'Civ'].shape[0], + 'mil_count': df[df["#CMPG"] == 'Mil'].shape[0], + 'pol_count': df[df["#CMPG"] == 'Pol'].shape[0], + 'gov_count': df[df["#CMPG"] == 'Gov'].shape[0], + 'aerobatic_count': category_df[category_df["Category"] == 'Aerobatic Teams'].shape[0], + 'air_corp_count': category_df[category_df["Category"] == 'Army Air Corp'].shape[0], + 'seen_on_tv_count': category_df[category_df["Category"] == 'As Seen on TV'].shape[0], + 'football_count': category_df[category_df["Category"] == 'Football'].shape[0], + 'britian_memorial_count': category_df[category_df["Category"] == 'Battle of Britain Memorial Flight'].shape[0], + 'big_hello_count': category_df[category_df["Category"] == 'Big Hello'].shape[0], + 'bizjets_count': category_df[category_df["Category"] == 'Bizjets'].shape[0], + 'climate_crisis_count': category_df[category_df["Category"] == 'Climate Crisis'].shape[0], + 'governments_count': category_df[category_df["Category"] == 'Governments'].shape[0], + 'coastguard_count': category_df[category_df["Category"] == 'Coastguard'].shape[0], + 'da_comrade_count': category_df[category_df["Category"] == 'Da Comrade'].shape[0], + 'dictator_count': category_df[category_df["Category"] == 'Dictator Alert'].shape[0], + 'distinctive_count': category_df[category_df["Category"] == 'Distinctive'].shape[0], + 'dogs_jobs_count': category_df[category_df["Category"] == 'Dogs with Jobs'].shape[0], + 'celeb_count': category_df[category_df["Category"] == "Don't you know who I am?"].shape[0], + 'flying_doctors_count': category_df[category_df["Category"] == 'Flying Doctors'].shape[0], + 'gaf_count': category_df[category_df["Category"] == 'GAF'].shape[0], + 'gas_bags_count': category_df[category_df["Category"] == 'Gas Bags'].shape[0], + 'gunship_count': category_df[category_df["Category"] == 'Gunship'].shape[0], + 'hired_gun_count': category_df[category_df["Category"] == 'Hired Gun'].shape[0], + 'historic_count': category_df[category_df["Category"] == 'Historic'].shape[0], + 'religious_count': category_df[category_df["Category"] == 'Jesus he Knows me'].shape[0], + 'joe_cool_count': category_df[category_df["Category"] == 'Joe Cool'].shape[0], + 'jump_johnny_count': category_df[category_df["Category"] == 'Jump Johnny Jump'].shape[0], + 'mash_count': category_df[category_df["Category"] == 'M*A*S*H'].shape[0], + 'nuclear_count': category_df[category_df["Category"] == 'Nuclear'].shape[0], + 'other_air_count': category_df[category_df["Category"] == 'Other Air Forces'].shape[0], + 'toy_soldiers_count': category_df[category_df["Category"] == 'Toy Soldiers'].shape[0], + 'other_navies_count': category_df[category_df["Category"] == 'Other Navies'].shape[0], + 'oxcart_count': category_df[category_df["Category"] == 'Oxcart'].shape[0], + 'psa_count': category_df[category_df["Category"] == 'Perfectly Serviceable Aircraft'].shape[0], + 'pia_count': category_df[category_df["Category"] == 'PIA'].shape[0], + 'police_forces_count': category_df[category_df["Category"] == 'Police Forces'].shape[0], + 'ptolemy_count': category_df[category_df["Category"] == 'Ptolemy would be proud'].shape[0], + 'quango_count': category_df[category_df["Category"] == 'Quango'].shape[0], + 'oligarch_count': category_df[category_df["Category"] == 'Oligarch'].shape[0], + 'radiohead_count': category_df[category_df["Category"] == 'Radiohead'].shape[0], + 'raf_count': category_df[category_df["Category"] == 'RAF'].shape[0], + 'royal_aircraft_count': category_df[category_df["Category"] == 'Royal Aircraft'].shape[0], + 'royal_navy_count': category_df[category_df["Category"] == 'Royal Navy Fleet Air Arm'].shape[0], + 'aerial_firefighter_count': category_df[category_df["Category"] == 'Aerial Firefighter'].shape[0], + 'special_forces_count': category_df[category_df["Category"] == 'Special Forces'].shape[0], + 'uav_count': category_df[category_df["Category"] == 'UAV'].shape[0], + 'uk_police_count': category_df[category_df["Category"] == 'UK National Police Air Service'].shape[0], + 'us_marines_count': category_df[category_df["Category"] == 'United States Marine Corps'].shape[0], + 'us_navy_count': category_df[category_df["Category"] == 'United States Navy'].shape[0], + 'usaf_count': category_df[category_df["Category"] == 'USAF'].shape[0], + 'vanity_plate_count': category_df[category_df["Category"] == 'Vanity Plate'].shape[0], + 'watch_fly_count': category_df[category_df["Category"] == 'Watch Me Fly'].shape[0], + 'that_thing_count': category_df[category_df["Category"] == "You came here in that thing?"].shape[0], + 'zoomies_count': category_df[category_df["Category"] == 'Zoomies'].shape[0], + 'ukraine_count': category_df[category_df["Category"] == 'Ukraine'].shape[0] + } + ) + )