Edit README to add structure & narrative

[scottveirs]

The current version of the README is a great start! I like the header image, the little "eye" emoji/icon, and the links you've added.

It could be improved in at least these two ways I think:

1. Add some additional headers (using e.g. the # ## ### syntax of MarkDown), maybe following the structure of this repo I recently enjoyed reading. (Lea used a brief intro and attribution guidance, then a background section, then add a couple of detail sections, then a final word section -- which for you could be an outline of your future/ongoing work plans).
2. Add full sentences around the content you've already got, aiming to explain the project to a pretty wide audience -- both computer scientists like yourself, but also marine scientists and bioacousticians like me who may not know much about machine learning.

[scottveirs]

Hey @tsuize , the README is looking more structured. Nice work!

Here are a few minor changes that I think you could make to improve the current draft:

• Add an attribution section to the very top. For now you could just put something like "Lead author: Ze Cui" and maybe link to your CoLab notebook(s), but later you could add here a Zenodo DOI, citation, or a note about the licensing of your code vs labeled data vs model(s)
• Instead of the numbered bullets, maybe use sub-section headers (e.g. ## or ###) to clearly and succinctly state each goal of the project (e.g. "Phase 1. Generate a labeled data set" and "Phase 2: Train model with labeled data")
• In first paragraph instead of "build a data set" consider instead writing something more specific like "build a labeled data set with at least 100 samples in each vessel class"
• Use the hypertext link syntax in Markdown language to add links to the text in the first paragraph for: beamreach.blue, protectedseas.net, and Roboflow.com
• In a couple places you write about "bounding box to be smaller than 50 pixels." It might be a little clearer if you wrote instead "bounding box with a minimum dimension of at least 50 pixels" or "bounding box with a minimum size of 50 pixels square"
• For "vesselDetection_071023" description, maybe add a screenshot of the Roboflow health assessment histogram to show distribution of sample sizes across all classes (after you've finished cleaning up labels and qualifiers)?
• In section number 2, break up that big, long paragraph into a few shorter ones. (It seems like the first few sentences may belong in the previous section?)
• The M2 system description is great. One minor improvement might be to replace the work "trip" with "transit."
• List your mentors at the very bottom in a new "Acknowledgments" (Sam, Val, Scott). There you could also thank Protected Seas for donating the M2 equipment to the project and Beam Reach (Val and Leslie!) for hosting the system at their home on San Juan Island.

[tsuize]

Thank you for your suggestions @scottveirs! I will change them accordingly.

[tsuize]

for the health check histogram, I will add later when all images are finished reviewing added to the dataset

[scottveirs]

@tsuize Just flagging the more detailed ideas we talked about today in a "top section", including:

• Make the first lines a sentence or two, rather than a sentence and a bullet point. (E.g. the first project is...)
• Bring a bit more intro text from below the video
• Take more credit, including listing yourself as point of contact (including how you want to be contacted!) and linking to LinkedIn or other personal site(s)
• summarize and link to each licenses (code, data, model)
  • specify attribution for the CC-BY-SA license
  • this is likely where we'll add any clauses regarding the RAIL (rather than modifying the RAIL itself)

[scottveirs]

@tsuize I noticed in the S3 bucket there seems to be a CC-BY license -- maybe from exporting data from Roboflow?

https://visual-sandbox.s3.us-west-2.amazonaws.com/orca-eye-aye/data/vesselDetection_071023/README.dataset.txt

that contains this text:

# vesselDetection > 2023-07-10 5:00pm
https://universe.roboflow.com/cuize/vesseldetection-dhmgv

Provided by a Roboflow user
License: CC BY 4.0

A good thing to discuss and investigate is whether you, @samcopeking / PS, and other partners want CC-BY or CC-BY-SA for the training data and/or model.

[samcopeking]

Can we discuss at our next meeting? Curious what examples might look like for either.

[tsuize]

Added all-class health check to the readme. "boat" is still showing in the classes... a bug fromRoboflow. But I guess it's ok since there is only one

[tsuize]

So far I have ticked off most of the tasks, leaving the license for tomorrow's discussion.