flyswot is a work in progress. Things may not work and behaviour may change in the future!
flyswot is a Command Line Tool which allows you to run Hugging Face Transformers image classification models available via the Hugging Face Hub 🤗 against a directory of images. It returns a CSV report containing the models predictions.
flyswot predict directory image_directory csv_reports --model_id flyswot/convnext-tiny-224_flyswot
Currently flyswot supports:
What is the point of this? Why not just write a Python script? This seems like a terrible idea...
flyswot was originally for a project with the Heritage Made Digital team at the British Library. In this project we wanted to detect 'fake flysheets'. We designed how flyswot works with this particular use case in mind.
There are a few main reasons why we decided a command line tool was the best approaches to utilising the models we were developing.
Since we're using computer vision for assisting rather than automation we felt a CLI was a useful interface for interacting with the models.
You can install flyswot via pip from PyPI:
$ pip install flyswot
This will install the latest release version of flyswot
Installation provides a more detailed guide to installing flyswot. This more detailed guide is aimed at users of flyswot who may be less familiar with Python.
You can see help for flyswot using flyswot --help
Usage: flyswot [OPTIONS] COMMAND [ARGS]...
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion [bash|zsh|fish|powershell|pwsh] Install completion for the specified shell. [default: None] │
│ --show-completion [bash|zsh|fish|powershell|pwsh] Show completion for the specified shell, to copy it or customize the installation. [default: None] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ model flyswot commands for interacting with models │
│ predict flyswot commands for making predictions │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
You can get help for the prediction functionality for flyswot as follows:
Usage: flyswot predict directory [OPTIONS] DIRECTORY CSV_SAVE_DIR
Predicts against all images stored under DIRECTORY which match PATTERN in the filename.
By default searches for filenames containing 'fs'.
Creates a CSV report saved to `csv_save_dir`
╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ * directory PATH Directory to start searching for images from [default: None] [required] │
│ * csv_save_dir PATH Directory used to store the csv report [default: None] [required] │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --model-id TEXT The model flyswot should use for making predictions [default: flyswot/convnext-tiny-224_flyswot] │
│ --pattern TEXT Pattern used to filter image filenames [default: None] │
│ --bs INTEGER Batch Size [default: 16] │
│ --image-formats TEXT Image format(s) to check [default: .tif] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
To run predictions against a directory of images:
$ flyswot predict directory manuscripts_folder .
FS in the filename since these are files which have been labelled as being "end flysheets" or "front flysheets"flysheet it will then run a computer vision model against these images to see if they are labelled correctly i.e. if it is indeed a flysheet or something else.You can also tell flyswot to use a different image classification model via the model-id parameter. For example to use the microsoft/dit-base-finetuned-rvlcdip model we could run:
flyswot predict directory Documents/DS/hugit-cli/fs Desktop/ --model-id microsoft/dit-base-finetuned-rvlcdip
This will download the latest available version of this model from the Hugging Face Hub and predict against the specified filenames. Note under the hood flyswot uses the Hugging Face transformers pipelines for inference. The model you specific must therefore be compatible with this pipeline.
This section provides additional guidance on the usage of flyswot. This is primarily aimed at HMD users of flyswot.
flyswot is currently intended to identify images which have an incorrect label associated with them. In particular it is currently intended to identify "fake" flysheets. These images have fs as part of their filename so we can tell flyswot to use this pattern in the filename to identify images which should be checked using the computer vision model. This can be changed if you also want to match other filename patterns.
Since these images of concern will often be inside a directory structure flyswot will look in sub-folders from the input folder for images which contain fs in the name. For example in the following folder structure:
Collection/
├─ item1/
│ ├─ add_ms_9403_fbspi.tif
│ ├─ add_ms_9403_fse001r.tif
│ ├─ add_ms_9403_fse001v.tif
├─ item2/
│ ├─ sloane_ms_116_fblefr.tif
│ ├─ sloane_ms_116_fbspi.tif
│ ├─ sloane_ms_116_fse004r.tif
All of the files which have fs in the filname will be check but files which don't contains fs such as add_ms_9403_fbspi.tif will be ignored since these aren't labelled as flysheets.
To run flyswot against a directory of images you need to give it the path to that directory/folder. There are different ways you could do this. The following is suggested for people who are not very familiar (yet 😜) with terminal interfaces.
Identify the folder you want to flyswot to check for "fake" flysheets. If you are using flyswot for the first time it may make sense to choose a folder which doesn't contain a huge number of collection items so you don't have to wait to long for flyswot to finish running. Once you have found a directory you want to predict against copy the path. This path should be the full path to the item.
For example something that looks like:
\\ad\collections\hmd\excitingcollection\excitingsubcollection\
This will be the folder from which flyswot starts looking.
When you activated your conda environment in a terminal, you were likely 'inside' your user directory. Since we need to specify a place for flyswot to store the CSV report, we'll move to a better place to store that output; your Desktop folder. To do we can navigate using the command:
$ chdir desktop
if you are using Mac, Linux or have GitBash installed you should instead run:
$ cd Desktop
This will take you to your Desktop. We'll now run flyswot. As with many other command line tools, flyswot has commands and sub-commands. We are interested in the predict command. This includes two sub-commands: predict-image and directory. We will mostly want to predict directories. To do this we use the following approach. Since we only care about checking things with fs in the filename we can specify this as our pattern.
$ flyswot predict directory input_directory output_directory --pattern fs
The input directory is the folder containing our images and the output directory is where we want to save our CSV report. Using the folder we previously identified this would look like:
$ flyswot predict directory "\\ad\collections\hmd\excitingcollection\excitingsubcollection\" .
We can use . to indicate we want the CSV report to be saved to the current directory (in this case the Deskop directory). Also notice that there are quotation marks "" around the path. This is used to make sure that any spaces in the path are escaped.
Once you run this command you should see some progress reported by flyswot, including a progress bar that shows how many of the images flyswot has predicted against.
When flyswot has finished you will have a CSV 'report' which contains the path to the image, the predicted label and the confidence for that prediction.
Distributed under the terms of the MIT license, flyswot is free and open source software.
If you encounter any problems, please file an issue along with a detailed description.
This project was generated from @cjolowicz's Hypermodern Python Cookiecutter template.
FAQs
flyswot
We found that flyswot demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.