diff --git a/docs/README.md b/docs/README.md index ef81b16e..e5b0f131 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,27 +1,22 @@ -# BioImage Model Zoo: Advanced AI models in one-click +# Welcome to BioImage.IO Documentation -The Bioimage Model Zoo is a community-driven AI model repository. The aim is to facilitate the adoption of AI methods among the bioimaging community by providing easy access to pretrained AI models. By establishing a common Model Resource Description File Specification, the model zoo serves as a distribution point for deep learning models trained to perform bioimage analysis tasks. +Welcome to the official BioImage.IO documentation. Here, you'll find comprehensive resources designed to support your journey through the fascinating world of bioimaging. Our documentation is structured to provide easy access to all the information you need, whether you're just starting out or looking to deepen your expertise. -Several founding partners including ilastik, ImJoy, Fiji, deepImageJ and ZeroCostDL4Mic are involved in the creation of the model zool and we welcome more community partners to join the efforts. Our vision is to define a common standard which would allow all models in the model zoo to be compatible with community partner tools. Such compatibility will ensure that the models in the model zoo can be interoperable between different tools and truly be used by non-computational biologists through user-friendly interface. +## Quick Navigation -In addition to the Model Resource Description File Specification, we aim to make cutting-edge AI technology accessible to our users by providing detailed model descriptions, tagging, searching and automatic testing of all submitted models. Models can be directly executed from the site with users' own data samples, and linked to its training data and Jupyter/Colab Notebooks. +- **[Getting Started](/getting_started/README.md)**: Introduction to the BioImage Model Zoo ecosystem, who are we and how can you be part of it. +- **[Guides](/guides/README.md)**: In-depth tutorials and guides regarding the BioImage Model Zoo as a user, contributor or Community Partner. +- **[Tools and Resources](/tools_and_resources/README.md)**: Overview of the available tools and resources linked to the BioImage Model Zoo. +- **[Help Desk](/help_desk/README.md)**: A bit lost? Check the help desk for more information, a glossary page and how to contact us! +- **[Terms of Service](/terms_of_service.md)**: Usage policies and guidelines. +- **[Code of Conduct](/CODE_OF_CONDUCT.md)**: The code of conduct for the ecosystem. -The model zoo is open for contributions from the community partners and external individuals. You are welcome to submit models to the model zoo. We will do our best to ensure you have a smooth experience contributing your work which will of course remain in your IP with all necessary attributions. +## Explore and Discover - +Dive into our documentation to explore the tools, resources, and support available to enhance your knowledge about the BioImage Model Zoo ecosystem. If you have any questions or need further assistance, our Help Desk is ready to assist you. Happy exploring! -# Reference publication +## Reference publication Wei Ouyang, Fynn Beuttenmueller, Estibaliz Gómez-de-Mariscal, Constantin Pape, Tom Burke, Carlos Garcia-López-de-Haro, Craig Russell, Lucía Moya-Sans, Cristina de-la-Torre-Gutiérrez, Deborah Schmidt, Dominik Kutra, Maksim Novikov, Martin Weigert, Uwe Schmidt, Peter Bankhead, Guillaume Jacquemet, Daniel Sage, Ricardo Henriques, Arrate Muñoz-Barrutia, Emma Lundberg, Florian Jug, Anna Kreshuk, **BioImage Model Zoo: A Community-Driven Resource for Accessible Deep Learning in BioImage Analysis**, bioRxiv 2022.06.07.495102, doi: [https://doi.org/10.1101/2022.06.07.495102](https://doi.org/10.1101/2022.06.07.495102) -# Glossary -In the ever-evolving field of bioimage analysis, understanding the terminology is essential. Explore our glossary to familiarize yourself with key terms and concepts used throughout the BioImage Model Zoo project. - -| Term | Definition | -| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Community Partner** | Usually, a community partner is an organization, a company, a research group, or a software team (of one or more) that can consume and/or produce resources of the BioImage Model Zoo. Additionally, most partners continuously and openly contribute resources of their own. The founders community partners represent open source consumer software of [BioImage.IO](http://BioImage.IO/) (e.g. [ilastik](https://www.ilastik.org), [Fiji](https://imagej.net/software/fiji/), [deepImageJ](https://deepimagej.github.io), [ZeroCostDL4Mic](https://github.com/HenriquesLab/ZeroCostDL4Mic), [StarDist](https://github.com/stardist/stardist)). A Community Partner can either be a team behind a software which produces or consumes trained models compatible with the [BioImage.IO](http://bioimage.io/) spec or an organization, group, company or team (of one or more) who contributed and will keep contributing more models to BioImage Model Zoo. | -| **Consumer** | Refers to an individual or user who engages with the project by utilizing the pre-existing models available on [BioImage.IO](http://bioimage.io/). Their primary role involves downloading these models and incorporating them into their workflow using compatible software or any specific manner that suits their needs. For example, a Life Scientist can be considered a consumer by accessing the[BioImage.io](http://bioimage.io/), selecting a Deep Learning model relevant to their research, and integrating it into their preferred software, such as deepImageJ or other compatible platforms. As a consumer, their focus lies in leveraging the existing models to enhance their bioimage analysis tasks, thereby benefiting from the diverse range of models provided by the BioImage Model Zoo. | -| **Contributor** | A contributor can either be an individual person or a group, entity, or software. As an individual contributor, your primary objective is to actively contribute to the project by uploading models to BioImage Model Zoo. By doing so, you expand the range of available models, enriching the repository and fostering the growth of the bioimage analysis community. As a contributor, you play a crucial role in sharing your expertise and innovative models with the broader community, contributing to advancements in bioimage analysis. Similarly, a software contributor refers to a software application or system that actively participates in the project by uploading models to [BioImage.IO](http://bioimage.io/). These software contributors enhance the available models by providing new and diverse solutions, further expanding the capabilities of the BioImage Model Zoo. Whether you contribute as an individual or a software entity, your active involvement in uploading models to [BioImage.IO](http://bioimage.io/) is instrumental in supporting the project's objectives. By sharing your models, you contribute to the collective knowledge and empower researchers in the bioimage analysis field. | -| **Consumer Software** | A consumer software refers to any software application or tool that utilizes the models from the BioImage Model Zoo repository. Consumer software is designed to interact with and make use of the pretrained AI models available in the BioImage Model Zoo. A consumer software is any software application or tool that utilize pretrained AI models for bioimage analysis tasks, either through integration, execution, or interaction with the models available in the BioImage Model Zoo. | -| **Model Resource Description File Specifications (RDF YAML)** | The Model Resource Description File (RDF) specifications refer to a set of guidelines that define the structure and content of a YAML file used to describe the AI models with pretrained weights in a standardized format. The model RDF serves as a metadata file that provides essential information about the model, its properties, and its intended use. The RDF file contains both mandatory and optional fields that capture relevant details about the model, such as its architecture, input/output formats, preprocessing steps, and performance metrics. By following the Model RDF specifications, developers and researchers can create consistent and interoperable descriptions of their AI models, allowing seamless integration and sharing within the [BioImage.IO](http://bioimage.io/) ecosystem. | \ No newline at end of file diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 2dd668e0..9de5f511 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,29 +1,8 @@ -* [Overview](/) -* [Getting Started](getting_started.md) -* [User Guide](/user_guide/README.md) - - [Model download](/user_guide/tutorials.md) - - [Use-case 1: Stardist H&E nucleus segmentation](usecase1stardist) - - [Use-case 2: 3D U-Net for cell-segmentation in light microscopy](usecase2finetune) - - [Use-case 3: Classification, imjoy & python library usage](usecase3devtools) - - [Use-case 4: Domain adaptation for mitochondria segmentation in EM](usecase4domain) - - [Contribution of resources](bioimageio_collection_repo) -* [BioEngine](/bioengine/README.md) - - [Tutorials](/bioengine/tutorials.md) -* [Contribute Models](/contribute_models/README.md) - - [Model Specification](bioimageio_model_spec) - - [Upload models through Zenodo](/contribute_models/contribute_zenodo.md) -* [Other contributions](/contribute_others/README.md) -* [Resources for developers](/resources_developers/README.md) -* [Consumer Software](/consumer_software/README.md) - - [Tutorials](/consumer_software/tutorials.md) - - [Model Runner](/consumer_software/model_runner.md) -* [Community Partners](/community_partners/README.md) - - [How to join](/community_partners/how_to_join.md) - - [User Analytics](/community_partners/user_analytics.md) - - [BioImage.IO Partner Collection](/community_partners/partner_collection.md) -* [FAQs](/faqs/README.md) +* [Welcome](/README.md) +* [Getting Started](/getting_started/README.md) +* [Guides](/guides/README.md) +* [Tools and Resources](/tools_and_resources/README.md) +* [Help Desk](/help_desk/README.md) * [Terms of Service](/terms_of_service.md) * [Code of Conduct](/CODE_OF_CONDUCT.md) -* [Governance](/bioimageio_steering.md) -* [BioImageIO team guidelines](https://github.com/bioimage-io/bioimage.io/wiki) diff --git a/docs/bioengine/README.md b/docs/deprecated/bioengine/README.md similarity index 100% rename from docs/bioengine/README.md rename to docs/deprecated/bioengine/README.md diff --git a/docs/bioengine/bioengine_apps.md b/docs/deprecated/bioengine/bioengine_apps.md similarity index 100% rename from docs/bioengine/bioengine_apps.md rename to docs/deprecated/bioengine/bioengine_apps.md diff --git a/docs/community_partners/README.md b/docs/deprecated/community_partners/README.md similarity index 77% rename from docs/community_partners/README.md rename to docs/deprecated/community_partners/README.md index ef954226..daeaf486 100644 --- a/docs/community_partners/README.md +++ b/docs/deprecated/community_partners/README.md @@ -176,16 +176,3 @@ api.export(new ImJoyPlugin()) ``` -| Tool Name | WebPage | Main Contact Person | Institution | Documentation | -| -------------- | ----------------------------------------- | --------------------------- | ------------------------------------------- | ------------------------------ | -| ZeroCostDL4Mic | [GitHub](https://github.com/HenriquesLab/ZeroCostDL4Mic) | Ricardo Henriques and Guillaume Jacquemet | [UTU](https://www.utu.fi/en) and [Abo Akademi](https://www.abo.fi) | [Wiki](https://github.com/HenriquesLab/ZeroCostDL4Mic/wiki) | -| DeepImageJ | [Website](https://deepimagej.github.io) | Arrate Muñoz Barrutia | [UC3M](https://www.uc3m.es/home) and [EPFL](https://www.epfl.ch/en/) | [Wiki](https://github.com/deepimagej/deepimagej-plugin/wiki) | -| ImJoy | [Website](https://imjoy.io/#/) | Wei Ouyang | [KTH](https://www.kth.se/en) | [Docs](https://imjoy.io/docs/#/) | -| Ilastik | [Website](https://www.ilastik.org) | Anna Kreshuk | [EMBL](https://www.embl.org) | [Docs](https://www.ilastik.org/documentation/index.html) | -| icy | [Website](https://icy.bioimageanalysis.org) | Jean-Christophe Olivo Marin | [IP](https://www.pasteur.fr/en) | - | -| Fiji | [Website](https://fiji.sc) | Florian Jug | - | [Docs](https://imagej.net/software/fiji/) | -| HPA | [Model Zoo](https://modelzoo.cellprofiling.org/#/) | Frederic Ballllosera Navarro | [KTH](https://www.kth.se/en) and [Stanford](https://stanford.edu) | - | -| QuPath | [Website](https://qupath.github.io) | Pete Bankhead | [UoE](https://www.ed.ac.uk) | [Docs](https://qupath.readthedocs.io/en/stable/) | -| StarDist | [Website](https://stardist.net) | Uwe Schmidt and Martin Weigert | - | [GitHub](https://github.com/stardist/stardist) | - - diff --git a/docs/community_partners/bioimage-io-community-partners.svg b/docs/deprecated/community_partners/bioimage-io-community-partners.svg similarity index 100% rename from docs/community_partners/bioimage-io-community-partners.svg rename to docs/deprecated/community_partners/bioimage-io-community-partners.svg diff --git a/docs/community_partners/contribute-test-summaries.md b/docs/deprecated/community_partners/contribute-test-summaries.md similarity index 100% rename from docs/community_partners/contribute-test-summaries.md rename to docs/deprecated/community_partners/contribute-test-summaries.md diff --git a/docs/community_partners/how_to_join.md b/docs/deprecated/community_partners/how_to_join.md similarity index 100% rename from docs/community_partners/how_to_join.md rename to docs/deprecated/community_partners/how_to_join.md diff --git a/docs/community_partners/partner_collection.md b/docs/deprecated/community_partners/partner_collection.md similarity index 100% rename from docs/community_partners/partner_collection.md rename to docs/deprecated/community_partners/partner_collection.md diff --git a/docs/community_partners/user_analytics.md b/docs/deprecated/community_partners/user_analytics.md similarity index 97% rename from docs/community_partners/user_analytics.md rename to docs/deprecated/community_partners/user_analytics.md index de315859..65c7c124 100644 --- a/docs/community_partners/user_analytics.md +++ b/docs/deprecated/community_partners/user_analytics.md @@ -2,7 +2,7 @@ We provide the analytics service to help consumer software to keep track of their resource (including model, datasets etc.) downloads. -## Report resource downloads +### Report resource downloads To help us maintain the resource download statistics at BioImage.IO, please send a report to our analytics service when a resource item is downloaded. @@ -22,7 +22,7 @@ In the above URL, you need to provide the following parameters: * `[CONSUMER VERSION]`: The software version for the consumer software. -## Obtain resource usage statistics +### Obtain resource usage statistics You can get the user statistics from via the HTTP API, for example: * To get the global statistics of the whole website: `https://bioimage.matomo.cloud/?module=API&method=Live.getCounters&idSite=1&lastMinutes=30&format=JSON&token_auth=anonymous` * To get the number of downloads: `https://bioimage.matomo.cloud/?module=API&method=Actions.getDownloads&idSite=1&period=year&date=2023-03-01&format=JSON&token_auth=anonymous` diff --git a/docs/consumer_software/README.md b/docs/deprecated/consumer_software/README.md similarity index 100% rename from docs/consumer_software/README.md rename to docs/deprecated/consumer_software/README.md diff --git a/docs/consumer_software/model_runner.md b/docs/deprecated/consumer_software/model_runner.md similarity index 100% rename from docs/consumer_software/model_runner.md rename to docs/deprecated/consumer_software/model_runner.md diff --git a/docs/consumer_software/tutorials.md b/docs/deprecated/consumer_software/tutorials.md similarity index 100% rename from docs/consumer_software/tutorials.md rename to docs/deprecated/consumer_software/tutorials.md diff --git a/docs/contribute_models/README.md b/docs/deprecated/contribute_models/README.md similarity index 100% rename from docs/contribute_models/README.md rename to docs/deprecated/contribute_models/README.md diff --git a/docs/contribute_models/contribute.md b/docs/deprecated/contribute_models/contribute.md similarity index 100% rename from docs/contribute_models/contribute.md rename to docs/deprecated/contribute_models/contribute.md diff --git a/docs/contribute_models/contribute_zenodo.md b/docs/deprecated/contribute_models/contribute_zenodo.md similarity index 93% rename from docs/contribute_models/contribute_zenodo.md rename to docs/deprecated/contribute_models/contribute_zenodo.md index ec498854..9ba69ee8 100644 --- a/docs/contribute_models/contribute_zenodo.md +++ b/docs/deprecated/contribute_models/contribute_zenodo.md @@ -1,6 +1,6 @@ # Uploading a Model to Zenodo for BioImage Model Zoo -**Note:** This tutorial provides a temporary solution for uploading models to the BioImage Model Zoo via Zenodo while the upload feature on the BioImage.io website is being fixed. +**Note:** This tutorial provides a temporary solution for uploading models to the BioImage Model Zoo via Zenodo while the upload feature on the BioImage.IO website is being fixed. ## Purpose This tutorial will guide you through the process of uploading a model to the BioImage Model Zoo community on Zenodo. The BioImage Model Zoo project aims to collect and share bioimage analysis models, and your contribution is valuable. Follow the steps below to upload your model. @@ -12,7 +12,7 @@ This tutorial will guide you through the process of uploading a model to the Bio Zenodo initial page 2. On the right, close to your username, click the "New upload" button to begin the model upload process. Make sure that the repository is set as public. -The files in the BioImage.io zip have to be uploaded one-by-one (See the example in the image below). Note that you can drag & drop all together at once. +The files in the BioImage.IO zip have to be uploaded one-by-one (See the example in the image below). Note that you can drag & drop all together at once. New upload @@ -28,4 +28,4 @@ The files in the BioImage.io zip have to be uploaded one-by-one (See the example ## Conclusion -You've successfully uploaded your model to the BioImage Model Zoo community on Zenodo. Thank you for your contribution to the BioImage Model Zoo project. Remember that this is a temporary solution while the upload feature on the BioImage.io website is being fixed. We appreciate your patience and support! +You've successfully uploaded your model to the BioImage Model Zoo community on Zenodo. Thank you for your contribution to the BioImage Model Zoo project. Remember that this is a temporary solution while the upload feature on the BioImage.IO website is being fixed. We appreciate your patience and support! diff --git a/docs/contribute_models/dummy_model_folder.png b/docs/deprecated/contribute_models/dummy_model_folder.png similarity index 100% rename from docs/contribute_models/dummy_model_folder.png rename to docs/deprecated/contribute_models/dummy_model_folder.png diff --git a/docs/contribute_models/enable_actions.png b/docs/deprecated/contribute_models/enable_actions.png similarity index 100% rename from docs/contribute_models/enable_actions.png rename to docs/deprecated/contribute_models/enable_actions.png diff --git a/docs/contribute_models/tutorials.md b/docs/deprecated/contribute_models/tutorials.md similarity index 100% rename from docs/contribute_models/tutorials.md rename to docs/deprecated/contribute_models/tutorials.md diff --git a/docs/contribute_others/README.md b/docs/deprecated/contribute_others/README.md similarity index 100% rename from docs/contribute_others/README.md rename to docs/deprecated/contribute_others/README.md diff --git a/docs/resources_developers/README.md b/docs/deprecated/resources_developers/README.md similarity index 100% rename from docs/resources_developers/README.md rename to docs/deprecated/resources_developers/README.md diff --git a/docs/user_guide/README.md b/docs/deprecated/user_guide/README.md similarity index 100% rename from docs/user_guide/README.md rename to docs/deprecated/user_guide/README.md diff --git a/docs/user_guide/explanations.md b/docs/deprecated/user_guide/explanations.md similarity index 100% rename from docs/user_guide/explanations.md rename to docs/deprecated/user_guide/explanations.md diff --git a/docs/user_guide/tutorials.md b/docs/deprecated/user_guide/tutorials.md similarity index 100% rename from docs/user_guide/tutorials.md rename to docs/deprecated/user_guide/tutorials.md diff --git a/docs/user_guide/welcome_slides.md b/docs/deprecated/user_guide/welcome_slides.md similarity index 100% rename from docs/user_guide/welcome_slides.md rename to docs/deprecated/user_guide/welcome_slides.md diff --git a/docs/wiki_files/resource_status_accepted.png b/docs/deprecated/wiki_files/resource_status_accepted.png similarity index 100% rename from docs/wiki_files/resource_status_accepted.png rename to docs/deprecated/wiki_files/resource_status_accepted.png diff --git a/docs/faqs/README.md b/docs/faqs/README.md deleted file mode 100644 index 47f9e811..00000000 --- a/docs/faqs/README.md +++ /dev/null @@ -1,48 +0,0 @@ -# FAQs - -Have questions about how to participate, contribute, or engage with the BioImage Model Zoo? Check out our Frequently Asked Questions (FAQs) for detailed answers and insights into making the most of your experience with our project. - -### How can I participate in the BioImage Model Zoo? - -To participate, you can take on the role of a **Community Partner** or engage as a **Consumer** or **Contributor** of models from the BioImage Model Zoo. - -- **Consumer**: As a Consumer, your role involves utilizing the existing models available on bioimage.io by downloading and incorporating them into your workflow using connected software or in any specific manner. For instance, a Life Scientist can be a Consumer by using a Deep Learning model downloaded from bioimage.io and integrating it into any compatible software (deepImageJ, Ilastik, ImJoy, ZeroCostDL4Mic, ...). - -- **Contributor**: If your primary objective is to contribute models to bioimage.io, then you are a Contributor. As such, you play a crucial role in expanding the range of available models and supporting the bioimage analysis community. - -### What is a Community Partner? Who can be a Community Partner? - -Usually, a **Community Partner** is an organization, a company, a research group, or a software team (of one or more) that can consume and/or produce models from/for the BioImage.IO Model Zoo. - -The first community partners represent open source consumer software of BioImage.IO (e.g. ilastik, Fiji, deepImageJ, ZeroCostDL4Mic, StarDist). - -A Community Partner can either be a team behind a software which produces or consumes trained models compatible with the BioImage.IO specifications or an organization, group, company, or team (of one or more) who contributes models to BioImage.IO. - - -### How can I upload a model to the BioImage Model Zoo? - -To contribute a model to the BioImage Model Zoo, please refer to the [Contribute Models section](https://bioimage.io/docs/#/contribute_models/README). This section provides detailed instructions on how to upload a model, including the necessary steps and required files for your contribution. - -### How can I report issues or provide feedback regarding models on BioImage.IO? - -If you encounter a bug or wish to share feedback, please use our [GitHub issues page](https://github.com/bioimage-io/bioimage.io/issues). We appreciate your input and kindly request that you ensure your feedback is not duplicated. Your contributions help improve the BioImage Model Zoo for the entire community. - -### What is AI4Life? - -AI4Life is a project whose goal is to provide sustainable, intuitive, and highest quality research services and infrastructures that will enable all life scientists to exploit machine learning to improve the utility and interpretability of image data, the key to future biomedical research. - -### How is AI4Life related to the BioImage Model Zoo? - -AI4Life is a project closely aligned with the BioImage Model Zoo. It plays a significant role in supporting and enhancing the BioImage Model Zoo's mission and initiatives. - -### Can I use models from the BioImage Model Zoo for commercial purposes? -Yes, you are welcome to use the models from the BioImage Model Zoo for commercial purposes. However, we kindly request that you provide appropriate credits when using these models as a gesture of acknowledgment for the contributions of the model creators and the BioImage Model Zoo community. - - -# Contact us - -If you can't find what you're looking for, there are several ways to communicate with us or get assistance. Here are some options: - -- You can ask a question or post in the [Image.sc Forum](https://forum.image.sc) using the tag 'bioimageio'. This way, not only our team but also others facing similar issues can benefit from your post. - -- Alternatively, you can contact us through our [contact form](https://oeway.typeform.com/to/K3j2tJt7), and someone will be available to assist with your questions. \ No newline at end of file diff --git a/docs/getting_started/README.md b/docs/getting_started/README.md new file mode 100644 index 00000000..084691ad --- /dev/null +++ b/docs/getting_started/README.md @@ -0,0 +1,38 @@ +# Getting Started + +## BioImage Model Zoo: Advanced AI models in one-click +The Bioimage Model Zoo is a community-driven AI model repository. The aim is to facilitate the adoption of AI methods among the bioimaging community by providing easy access to pretrained AI models. By establishing a common Model Resource Description File Specification, the model zoo serves as a distribution point for deep learning models trained to perform bioimage analysis tasks. + +Several founding partners including ilastik, ImJoy, Fiji, deepImageJ and ZeroCostDL4Mic are involved in the creation of the model zool and we welcome more community partners to join the efforts. Our vision is to define a common standard which would allow all models in the model zoo to be compatible with community partner tools. Such compatibility will ensure that the models in the model zoo can be interoperable between different tools and truly be used by non-computational biologists through user-friendly interface. + +In addition to the Model Resource Description File Specification, we aim to make cutting-edge AI technology accessible to our users by providing detailed model descriptions, tagging, searching and automatic testing of all submitted models. Models can be directly executed from the site with users' own data samples, and linked to its training data and Jupyter/Colab Notebooks. + +The model zoo is open for contributions from the community partners and external individuals. You are welcome to submit models to the model zoo. We will do our best to ensure you have a smooth experience contributing your work which will of course remain in your IP with all necessary attributions. + + + +Here there are some slides to ilustrate how the BioImage Model Zoo works. Press the **RUN** button to show the slides. + +```js +api.showDialog({src: "https://slides.imjoy.io/?slides=https://raw.githubusercontent.com/esgomezm/bioimage.io/main/docs/user_guide/welcome_slides.md"}) +``` + +## How to participate in the BioImage Model Zoo +Participation into the BioImage Model Zoo is opened to many different profiles. None of them exclude any other. Here are the options in which you can intereact with the BioImage Model Zoo: + +### As a User or Consumer of models, applications or datasets +Act as a user in the BioImage Model Zoo refers to an individual or user who engages with the project by utilizing the pre-existing models available on [BioImage.IO](http://bioimage.io/). Their primary role involves downloading these models and incorporating them into their workflow using compatible software or any specific manner that suits their needs. For example, a Life Scientist can be considered a consumer by accessing the[BioImage.IO](http://bioimage.io/), selecting a Deep Learning model relevant to their research, and integrating it into their preferred software, such as deepImageJ or other compatible platforms. As a consumer, their focus lies in leveraging the existing models to enhance their bioimage analysis tasks, thereby benefiting from the diverse range of models provided by the BioImage Model Zoo. + +### As a Contributor or developer of models, applications or datasets +A contributor or developer can either be an individual person or a group, entity, or software. As an individual contributor, your primary objective is to actively contribute to the project by uploading models to BioImage Model Zoo. By doing so, you expand the range of available models, enriching the repository and fostering the growth of the bioimage analysis community. As a contributor, you play a crucial role in sharing your expertise and innovative models with the broader community, contributing to advancements in bioimage analysis. Similarly, a software contributor refers to a software application or system that actively participates in the project by uploading models to [BioImage.IO](http://bioimage.io/). These software contributors enhance the available models by providing new and diverse solutions, further expanding the capabilities of the BioImage Model Zoo. Whether you contribute as an individual or a software entity, your active involvement in uploading models to [BioImage.IO](http://bioimage.io/) is instrumental in supporting the project's objectives. By sharing your models, you contribute to the collective knowledge and empower researchers in the bioimage analysis field. + +### As a Community Partner +Usually, a community partner is an organization, a company, a research group, or a software team (of one or more) that can consume and/or produce resources of the BioImage Model Zoo. Additionally, most partners continuously and openly contribute resources of their own. The founders community partners represent open source consumer software of [BioImage.IO](http://BioImage.IO/) (e.g. [ilastik](https://www.ilastik.org), [Fiji](https://imagej.net/software/fiji/), [deepImageJ](https://deepimagej.github.io), [ZeroCostDL4Mic](https://github.com/HenriquesLab/ZeroCostDL4Mic), [StarDist](https://github.com/stardist/stardist)). A Community Partner can either be a team behind a software which produces or consumes trained models compatible with the [BioImage.IO](http://bioimage.io/) spec or an organization, group, company or team (of one or more) who contributed and will keep contributing more models to BioImage Model Zoo. + +## AI4Life and the BioImage Model Zoo +AI4Life is a project closely aligned with the BioImage Model Zoo. It plays a significant role in supporting and enhancing the BioImage Model Zoo's mission and initiatives. +To learn more about AI4Life, please visit the [AI4Life Help Desk](https://ai4life.eurobioimaging.eu/help/). +Access training materials and videos on the Galaxy Training Network to enhance your understanding of AI4Life and the BioImage Model Zoo [here](https://training.galaxyproject.org/training-material/topics/ai4life/). + +## Commercial use of the BioImage Model Zoo +Resources from the BioImage Model Zoo are free to use for commercial purposes. However, we kindly request that appropiate credits are provided when using these resources as a gesture of acknowledgment for the contributions of the model creators and the BioImage Model Zoo community. Please refer to the Reference publication section for more information. \ No newline at end of file diff --git a/docs/bioimage_description.png b/docs/getting_started/bioimage_description.png similarity index 100% rename from docs/bioimage_description.png rename to docs/getting_started/bioimage_description.png diff --git a/docs/guides/README.md b/docs/guides/README.md new file mode 100644 index 00000000..b6875e88 --- /dev/null +++ b/docs/guides/README.md @@ -0,0 +1,557 @@ +# Guides +The BioImage Model Zoo is intended to be used by different roles in the community as stated in [How to participate in the BioImage Model Zoo](/getting_started/README.md). This section contains guides for the different roles in the community. + +## Content +* **[User Guide](#user-guide)**: Guides for users willing to download and use the models and other resources from the BioImage Model Zoo +* **[Developers Guide](#developers-guide)**: Guides for who is willing to contribute to the BioImage Model Zoo with models, applications or softwares. +* **[Community Partners Guide](#community-partners-guide)**: If you want to join as a Community Partner, this is your place to visit. + +## User Guide +This guide is intended for users wanting to consume or use models from the BioImage Model Zoo. There are plenty of models in the BioImage Model Zoo that you can use in your own software, in the software of our community partners or you can even download them and use them in a notebook or code of your own. + +### Downloading and using Models from the BioImage Model Zoo + +See a [video](https://oc.embl.de/index.php/s/eJOIdzDVJpToETd) about using a model from the BioImage Model Zoo in different software. + +bioimage.io download + + +### Using BioImage Model Zoo models in different software + +#### BiaPy +TBD + +#### DeepImageJ + +**Note: deepImageJ supports PyTorch and Tensorflow 1 models** + +1. Install the [deepImageJ plugin](https://deepimagej.github.io/download.html) in ImageJ. +This will give you all the necessary Plugins to run bioimage.io models at the moment. + +2. Install a model from the [BioImage Model Zoo](https://bioimage.io/): + 1) Download a deepImageJ model from the BioImage Model Zoo repository. + 2) Use `DeepImageJ Install Model` in ImageJ to install the `.zip` file that you just downloaded: choose the `Private model` option and `From ZIP file`. + 3) In the `zip` file you just downloaded, there is an `exampleImage.tif`that you can open in ImageJ and process with the model you just downloaded. + 4) See a detailed tutorial [here](https://deepimagej.github.io/tutorials.html). + +For more detailed information about the connection between the BioImage Model Zoo and deepImageJ, see deepImageJ wiki [here](https://github.com/deepimagej/deepimagej-plugin/wiki/BioImage-Model-Zoo-Connection). + +#### Fiji +**Note: Fiji only supports Tensorflow 1 models at the moment!** + +1. Install the [CSBDeep-Plugin](https://github.com/CSBDeep/CSBDeep_website/wiki/CSBDeep-in-Fiji-%E2%80%93-Installation) in Fiji. +This will give you all the necessary Plugins to run bioimage.io models at the moment. +2. Open the image you want to run the model on +3. a) If your model is a [CSBDeep](https://imagej.net/CSBDeep) one, go to Plugins > CSBDeep and choose either "N2V", "DenoiSeg" or "Run your network"(default) + + b) For any other bioimage.io model, go to Plugins > bioimage.io > bioimage.io prediction. +4. Continuing from 3b) you will arrive at this window: + +Fiji bioimage.io prediction + +The configuration fields should be self-explanatory. + +5. Click "OK" to run the model prediction. + + +#### Ilastik +TBD + +#### ImJoy +TBD + + +#### ZeroCostDL4Mic +**Note: [ZeroCostDL4Mic](https://github.com/HenriquesLab/ZeroCostDL4Mic/wiki) allows you trainig models and upload them to the BioImage Model Zoo or fine-tune existing ones!** + +1. Download a ZeroCostDL4Mic model from the [BioImage Model Zoo](https://bioimage.io/) repository. +2. Unzip the model `.zip` file so you can use it later in the notebook. +3. Open the ZeroCostDL4Mic notebook that corresponds to the model you downloaded. +4. When required, specify the path to the unziped folder containing the model. + +### Best Practices for Model Usage +TBD + +### Use Cases +- [Use-case 1: Stardist H&E nucleus segmentation](https://github.com/bioimage-io/use-cases/tree/main/case1-stardist) +- [Use-case 2: 3D U-Net for cell-segmentation in light microscopy](https://github.com/bioimage-io/use-cases/tree/main/case2-finetuning) +- [Use-case 3: Classification, imjoy & python library usage](https://github.com/bioimage-io/use-cases/tree/main/case3-devtools) +- [Use-case 4: Domain adaptation for mitochondria segmentation in EM](https://github.com/bioimage-io/use-cases/tree/main/case4-research) + +## Developers Guide + +### Models in the BioImage Model Zoo +A BioImage.IO model is a zip file containing all the items, technical description and metadata of the model, together with the trained architecture of the model. Briefly, a BioImage.IO model has at least, the following items: +* Trained model in the correct format (check the Resource Description File Specifications for the [supported formats](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/user_docs/model_descr_latest.md)) +* Example input image (numpy array) +* Example output (numpy array) +* Resource description file specifications (`rdf.yaml`) +* An example cover image for visual representation of the model in the zoo. + +In some cases, the model may need additional files. + +#### Model contribution requirements + +- Follow the [BioImage.IO Model Resource Description File Specification (RDF)](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/user_docs/model_descr_latest.md) with `format_version>= 0.4.5`. +- The model is expected to be cross-compatible among the consumer software, and should always run on at least one. +- The model should be well documented (i.e., human readable name and rich description tailored for life-scientists, citations) +- The model should be public and can be used by anyone under the chosen licensing conditions. + +#### Upload a model to the BioImage Model Zoo + +**1. Create a BioImage.IO model** +Two options: + 1. Choose one way to create your model: + - Automatic export of the model using the [bioimageio.core python library](https://github.com/bioimage-io/core-bioimage-io-python) (recomended). + Example code [here](https://github.com/bioimage-io/core-bioimage-io-python/blob/main/example/model_creation.ipynb). + - The main function to build the model is `bioimageio.core.build_model`. Check its input variables to know what has to be provided. + - Manual generation of the model: + - Create the [BioImage.IO Model Resource Description File Specifications](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/user_docs/model_descr_latest.md) (`rdf.yaml` file). + - Each field on the file is either mandatory or optional. In the Bioimage Model Zoo web page you can find different examples. + 2. Check that the model is correctly created: + - Static validation of the model format using the [bioimageio.core python library](https://github.com/bioimage-io/core-bioimage-io-python) library (*e.g.*, in the terminal, `bioimageio validate /../rdf.yaml`). + - Dynamic validation of the model's deployment (*e.g.*, in the terminal, `bioimageio test-model --weights tensorflow_saved_model_bundle --device cpu /.../rdf.yaml`). It tests that the model generates the expected output. + +**2. Upload the model to the BioImage Model Zoo** + +To upload a model to the BioImage Model Zoo, you have a tutorial video of the process step by step available [here](https://oc.embl.de/index.php/s/JBWwJGgsXh0vYM6). + + + +For a detailed explanation, follow these steps: +1. In [BioImage.IO](https://bioimage.io/), click on `+Upload` and follow the steps: + +2. Log in to Zenodo and give access to the BioEngine application. You will see an automatic message once you are logged in. If not, refresh the page. This step needs to be done only for the first time you upload a model. + +3. Upload your model RDF. + + +4. Complete the missing fields. + + + + +5. A [Pull Request (PR)](https://github.com/bioimage-io/collection-bioimage-io/pulls/bioimageiobot) is generated (this process may take some minutes). In the PR, the model is tested by a Continuous Integration (CI) workflow for its technical correctness. and reviewed by a maintainer from the BioImage.IO team. This PR is aimed for further discussions between model contributors and the BioImage.IO team. + +6. Once the model passes all checks and has the approval of a maintainer, it will be added to the BioImage.IO collection and displayed in the webpage (this process may take some minutes). + +#### Upload a model through Zenodo +**Note:** This tutorial provides a temporary solution for uploading models to the BioImage Model Zoo via Zenodo while the upload feature on the BioImage.IO website is being fixed. + +This tutorial will guide you through the process of uploading a model to the BioImage Model Zoo community on Zenodo. The BioImage Model Zoo project aims to collect and share bioimage analysis models, and your contribution is valuable. Follow the steps below to upload your model. + +1. Open your web browser and navigate to the Zenodo website at [https://zenodo.org/](https://zenodo.org). You need to create a Zenodo account if you do not have one. + + Zenodo initial page + +2. On the right, close to your username, click the "New upload" button to begin the model upload process. Make sure that the repository is set as public. +The files in the BioImage.IO zip have to be uploaded one-by-one (See the example in the image below). Note that you can drag & drop all together at once. + + New upload + +3. Add `bioimage.io` on Keywords and subjects. This is crucial for us to identify your submission. + + Find BioImage.IO community + +4. Follow the on-screen instructions to provide the required information about your model. Make sure to include a clear description, relevant tags, and any necessary documentation. + +5. Once finished, click on Submit. + +6. Your model will be proposed as a new contribution to the BioImage Model Zoo automatically. If the model passes all the tests, it will be automatically displayed in the Zoo. If the model does not pass the test, the GitHub users indicated in `maintainers` in the `rdf.yaml` file will be noitified through GitHub. This process can take 12-24h. + +You've successfully uploaded your model to the BioImage Model Zoo community on Zenodo. Thank you for your contribution to the BioImage Model Zoo project. Remember that this is a temporary solution while the upload feature on the BioImage.IO website is being fixed. We appreciate your patience and support! + + +#### Model Documentation +##### Model naming + +Models are expected to be used by life-scientists, thus, it is expected that the naming is human readable but also informative enough regarding the final application and the biological tissue being analysed. Example: + + **Name:** `Neuron Segmentation in EM (Membrane Prediction)`, `B. Sutilist bacteria segmentation - Widefield microscopy - 2D UNet` + + +##### Model Tags +The tags in the model RDF are used to search for each model in the BioImage Model Zoo. The more informative tags you write, the easier it will be for a potential user to find your model. Example: + + **My model description**: An encoder-decoder trained for denoising of point-scanning super-resolution microsocpy images of HeLa cells microtubules + + **Tags**: `denoising`, `PSSR`, `microtubules`, `encoder-decoder`, `deblurring`, `fluorescence`, `2D`, `HeLa cells`, `deepimagej`, `ilastik`, `image restoration`, `trained-model` etc. + +##### Model links +The BioImage Model Zoo is a software webpage. Each model is displayed with an interactive card that can have datasets, notebooks, applications, consumer-software or test-run buttons linked. Example: + + **Links**: `imjoy/BioImageIO-Packager`, `ilastik/ilastik`, `deepimagej/deepimagej`, `zero/dataset_fnet_3d_zerocostdl4mic` etc. + +##### Representative Covers + +You can include different cover images that represent the analysed tissue, imaging modality, image processing task and the performance of the model. This image will be used in the model card to guide the users through the model search. + + +#### Considerations for the model description file + +When following the BioImage.IO model RDF specification provided at https://github.com/bioimage-io/spec-bioimage-io, it is important that you pay special attention to the following: +* Choose test input image(s) and generate the respective test output tensor(s). This enables our scripts to test your model for technical correctness and to test which [consumer software](https://bioimage.io/docs/#/consumer_software/model_runner) can process it. +* Pre-processing and post-processing should be always described. You can check which [preprocessing](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/preprocessing_spec_latest.md) and [postprocessing](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/postprocessing_spec_latest.md) functions are supported at the moment and open an [issue here](https://github.com/bioimage-io/spec-bioimage-io/issues) if you are missing a specific operation. +* Do not forget to include any additional files needed for the correct execution of the model during the upload process. + +### Other contributions +You are welcome to submit your **models**, **datasest**, **applicaitons** and Jupyter **notebooks** to BioImage.IO. + +To add an resource item to BioImage.IO, you need to provide a set of basic information about the resouce, including name, description, authors etc. and we will generate a resource card to display in the website. + +For Community Partners, you can add models directly to the linked repository. If you are not part of the community partners, you can follow the instructions below to submit resource items (models, datasets etc.) to BioImage.IO. + +#### Submit to BioImage.IO +* Step 1, prepare a [`Resource Description File`](/bioimageio_rdf_spec)(RDF) and complete at least the mandatory fields and ideally also the recommended fields for different types of resource. + +* Step 2, save the RDF file in one of the public git hosting website, it is recommended to store the RDF file in your project git repository on Github/Gitlab/Bitbucket (make sure it's a public repo). Alternatively, you can post it on [Gist](https://gist.github.com/), copy the the **raw** url to the actual file content. + +* Step 3, post the url to the comment box below (if you don't see it, click [here](https://github.com/bioimage-io/bioimage-io-models/issues/26)). And the admin team will check and verify the format and incooperate to BioImage.IO if the submitted file is qualified. + +## Community Partners Guide +BioImage.IO is a community-driven open source initiative, providing access to trained deep learning models and related resources contributed by the community members. To help us better disseminate and maintain the resources, we introduced the concepts of **community partner**. + +### Introduction to Community Partners + +#### What is a community partner? +Usually, a community partner is an organization, a company, a research group, or a software team (of one or more) that can consume and/or produce resources of the BioImage.Io model zoo. Additionally, most partners continuously and openly contribute resources of their own. The first community partners represent open source consumer software of BioImage.IO (e.g. ilastik, Fiji, deepImageJ, ZeroCostDL4Mic, StarDist). + +#### Benefits as a community partner +By joining BioImage.IO as a community partner, you will be able to: + - Participate in decision making process of the model specification. + - Show your logo in BioImage.IO and enable filtering models by compatibility with your software. + - Connect CI to automatically test new model compatibility with your software and use other infrastructure features provided by BioImage.IO. + +#### Responsibilities +The main responsibilities of a community partner are: + - Use BioImage.IO as their only primary trained model repository. + - Review resources contributed by others that claim to be compatible with this community partner software. + - Maintain this community partner's models and other resources in their linked repository, setup continous integration workflows to test models and keep them up-to-date with the latest spec. + +#### Who should join as a community partner? + * A team behind a software which produces or consumes trained models compatible with the BioImage.IO spec. + * A organization, group, company or team (of one or more) who contributed and will keep contributing more models to BioImage.IO. + +#### How does it work? +Community partners can host their own Github repository for storing models and other resources that are relevant. These resources are listed in a [collection RDF](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/collection_spec_latest.md)–a yaml file–which will be dynamically linked to the [central repository of BioImage.IO](https://github.com/bioimage-io/bioimage-io-models). The [continuous integration (CI) service](https://github.com/bioimage-io/bioimage-io-models/actions) configured in the central repo will then pull the resources from partners' repo and compile them into items displayed in the BioImage.IO website. Each community partner is responsible for maintaining the resources that are relevant. + +![bioimage-io-community-partners](./community_partners_guide/bioimage-io-community-partners.png) + +### Meet our Community Partners +Below is a list of our esteemed Community Partners who actively engage with the BioImage Model Zoo project, contributing their expertise, resources, and support to enhance the bioimage analysis community. + + +```html + +{ + "name": "BioImageIO Community Partners", + "type": "window", + "tags": [], + "ui": "", + "version": "0.1.0", + "cover": "", + "description": "Create a table for the bioimage.io community partners", + "icon": "extension", + "inputs": null, + "outputs": null, + "api_version": "0.1.8", + "env": "", + "permissions": [], + "requirements": ["https://cdnjs.cloudflare.com/ajax/libs/react/17.0.2/umd/react.production.min.js", "https://cdnjs.cloudflare.com/ajax/libs/react-dom/17.0.2/umd/react-dom.production.min.js", "https://cdnjs.cloudflare.com/ajax/libs/babel-standalone/6.26.0/babel.min.js", "https://cdn.tailwindcss.com"], + "dependencies": [], + "defaults": {"w": 20, "h": 10} +} + + + +// Main React App Component +const App = () => { + const [partners, setPartners] = React.useState([]); + + // Fetch JSON data from the URL + React.useEffect(() => { + fetch('https://raw.githubusercontent.com/bioimage-io/collection-bioimage-io/gh-pages/collection.json') + .then(response => response.json()) + .then(data => { + if (data.config && data.config.partners) { + setPartners(data.config.partners); + } else { + setPartners([]); + } + }) + .catch(err => console.error(err)); + }, []); + + return ( +
+
+

Community Partners

+ + + + + + + + + + {partners.map((partner, index) => ( + + + + + + ))} + +
Community PartnerDocumentationContact
{partner.name || 'N/A'}{partner.docs || 'N/A'} + {partner.contact ? ( + partner.contact.map((contact, i) => ( +
+
Name: {contact.name || 'N/A'}
+
Github: {contact.github || 'N/A'}
+
Email: {contact.email || 'N/A'}
+
+ )) + ) : ( + 'N/A' + )} +
+
+
+ ); +}; + +// Render the App component +ReactDOM.render(, document.getElementById('root')); + + + + + +
+ + + +``` + + +### How to join as a community partner? + +Note that in order to contribute resources to the BioImage.IO Model Zoo you do not need to become a community partner. How to contribute resources is described [here](/contribute_models/README.md). The role of a community partner is described [here](/community_partners/README.md). + + +If you are eligible and willing to join as a community partner, please submit a request issue [here](https://github.com/bioimage-io/collection-bioimage-io/issues/new) with relevant information including the following: +1. Description of your software, organization, company or team. +2. Description of the resources that you plan to contribute. Please also include the url to your project repo. +3. Description of future plans on how your project will be maintained. + +The admin team of BioImage.IO will discuss the request and decide whether to approve or decline. We will mainly check whether the project are beneficial for the users of BioImage.IO and the requirements for participation are met. + +Upon approval, we will guide you to follow these steps in order to incorporate your contribution to BioImage.IO: + +1. Firstly, please create or choose a GitHub repo for hosting your resource collection that you would like to contribute. We recommend to create a dedicated repository in your organization for this purpose. As an example you might want to take a look at the [ilastik collection](https://github.com/ilastik/bioimage-io-resources/blob/main/collection.yaml). +1. Add a [collection RDF](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/collection_spec_latest.md) in your chosen repository, which lists all resources you would like to contribute. For this, you will also need to prepare the icons of your software or project. +1. Setup CI service for testing your collection RDF. Please refer to [how to setup CI service](/community_partners/how_to_join?id=how-to-setup-ci-service-for-a-community-partners39-repo). +1. Make a PR (or an issue) in the BioImage.IO Collection repo to link your collection to the [collection_rdf_template.yaml](https://github.com/bioimage-io/collection-bioimage-io/blob/main/collection_rdf_template.yaml)(under `config.partners`). We only require the link to your collection RDF here and need to agree on a partner id for you. +1. To make the maintainance easier, we also ask you to add one of the admin member as collabrators in your resource collection repository. This will make it easier for us to help you maintaining your collection, and keep synchronized in case we make changes to the specification. + +### How to register a software or application? + +A community partner can have one or multiple associated software, you can register them in the collection RDF file of your repository (see the previous section about creating a collection repository). A software is categorized as "Application" in the BioImage Model Zoo. The first thing to do is to create an application file in the [ImJoy plugin file format](https://imjoy.io/docs/#/development?id=plugin-file-format). This basically allows you define a landing page for your software with executable features such as download or test run buttons for your software. The most common use case is to create a landing page for your software. Each software will have an unique id, typically in the format of `/`. Every model can add links (manually when upload or automatically via the CI) to the software. For each model, the user can click the link on top of the model card, and the landing page will be loaded. Through the ImJoy plugin mechanism, the context information contains the current model information will be injected to the landing page, it's up to the developer who made the software app to decided how to use those information. + +To see an example, you can find the [source for the ilastik app](https://github.com/ilastik/bioimage-io-resources/blob/main/src/ilastik-app.imjoy.html) and also the corresponding entry in the collection file [here](https://github.com/ilastik/bioimage-io-resources/blob/2d2f1b12b185b1b880bfb679ed2aa981bf88d1ed/collection.yaml#L45-L59). + +### How to setup CI service for a community partners' repo? + +The CI service is an useful tool to autotomize the maintenance of the model repo and ensure a high quality for all BioImage.IO resources. +You basically need to add some testing scripts to your repo and configure it using CI services such as Github Actions, Travis or Circle CI etc. The testing script will be triggered by a new commit or pull request to the repo. For simplicity, we recommend Github Actions which can be triggered by adding a yaml file under the folder `.github/workflows`. For example, here is an example file [.github/workflows/compile-manifest.yml](https://github.com/deepimagej/models/blob/master/.github/workflows/compile-manifest.yml) that we used to verify the model spec in the central repo. + +There are at least three steps are recommended: + 1. Run the [`compile_model_manifest.py`](https://github.com/bioimage-io/bioimage-io-models/blob/master/manifest.bioimage.io.yaml) script to make sure the manifest can be correctly compiled. + 2. Verify the yaml files according to model spec with [.github.com/bioimage-io/python-bioimage-io](https://github.com/bioimage-io/python-bioimage-io). + 3. If possible, test every models added to the repo. + +As a start, you can use [.github/workflows/compile-manifest.yml](https://github.com/deepimagej/models/blob/master/.github/workflows/compile-manifest.yml) as your template. + +See more information here: https://github.com/bioimage-io/collection-bioimage-io#contribute-resource-test-summaries + +### Report User Analytics + +We provide the analytics service to help consumer software to keep track of their resource (including model, datasets etc.) downloads. + +#### Report resource downloads + +To help us maintain the resource download statistics at BioImage.IO, please send a report to our analytics service when a resource item is downloaded. + +Under the hood, we use [matomo](https://matomo.org) to track the user downloads. It provide tracking api in various programming languages and frameworks, see here: https://developer.matomo.org/api-reference/tracking-api. + +The easiest way to report a model download is to send an http request to matomo. + + +You need to construct an URL to report the download: + +`https://bioimage.matomo.cloud/matomo.php?download=https://doi.org/[MODEL DOI]&idsite=1&rec=1&r=646242&h=13&m=35&s=20&url=http://bioimage.io/#/?id=[MODEL DOI]&uadata={"brands":[{"brand":"[CONSUMER ID]","version":"[CONSUMER VERSION]"}]}` + + +In the above URL, you need to provide the following parameters: + * `[MODEL DOI]`: The resource doi, it should be similar to `10.5281/zenodo.55555555`. Also note that Zenodo deposit has concept doi and version doi, we recommend to use the concept doi such that the downloads across versions can be aggregated. + * `[CONSUMER ID]`: The id for the registered consumer software, for example: `ilastik` or `deepimagej`. + * `[CONSUMER VERSION]`: The software version for the consumer software. + + +#### Obtain resource usage statistics +You can get the user statistics from via the HTTP API, for example: + * To get the global statistics of the whole website: `https://bioimage.matomo.cloud/?module=API&method=Live.getCounters&idSite=1&lastMinutes=30&format=JSON&token_auth=anonymous` + * To get the number of downloads: `https://bioimage.matomo.cloud/?module=API&method=Actions.getDownloads&idSite=1&period=year&date=2023-03-01&format=JSON&token_auth=anonymous` + * To get the number of downloads for a specific resource (via DOI): ```https://bioimage.matomo.cloud/?module=API&method=Actions.getDownload&downloadUrl=https://doi.org/`[MODEL DOI]`&idSite=1&period=year&date=2023-03-01&format=JSON&token_auth=anonymous```. To see an example, click here: https://bioimage.matomo.cloud/?module=API&method=Actions.getDownload&downloadUrl=https://doi.org/test&idSite=1&idCustomReport=1&period=year&date=2023-03-01&format=JSON&token_auth=anonymous + + For more detailed API, see here: https://developer.matomo.org/api-reference/reporting-api + + +Please note that the reports are not processed in realtime, this means you won't see the statistics for your reports immediately: + - In the report request, we need to configure the date properly. For example, we can change period to `year` and date to `2023-03-01` (see here: https://developer.matomo.org/api-reference/Piwik/Period) + - The report will only be generated every 15 minutes: https://matomo.org/faq/general/faq_41/ so we won't see the report immediately. + +### BioImage.IO Partner Collection + +A BioImage.IO partner collection is a YAML file in GitHub repository of a community partner. The file adheres to the collection RDF specification described [here](https://github.com/bioimage-io/spec-bioimage-io#collection-resource-description-file-specification). + +The appearance of the partner collection on the website can be customized by the `config` field as described in the next section. + +#### Customizing appearance on bioimage.io + +Like any RDF, a collection RDF may have a `config` field to hold non-standardized metadata. We currently use some of this metadata to customize the partner collection appearance on the bioimage.io website. The fields used here are subject to change, but as a community partner we'll keep you in the loop on any changes here and will likely formalize this part in the future. + +A typical partner collection RDF `config` field may look like this: + +```yaml +config: + # a url for the user to get more details about the collection or your project + # it can be a markdown file (*.md) hosted on github, you need to use the `raw` url + # or an external link to your website + about_url: http://details_about_my_collection + + # these tags will be used to filter items when the user select this collection + tags: + - awesome + + # the logo for the collection, you can use an emoji or a url to a png/jpg/gif/svg image + logo: 🦒 + + # the icon for your collection you can use an emoji or a url to a png/jpg/gif/svg image + # note, this must be a square or contained in a square + icon: 🦒 + + + # settings for the splash screen + splash_title: Awesome Collection + splash_subtitle: Awesome Collection is Awesome! + splash_feature_list: + - Easy to use... + - It's just awesome... + explore_button_text: Start Awesomeness + background_image: static/img/zoo-background.svg + + # the available resource types in your collection + resource_types: + - model + - application + - notebook + - dataset + + # the default resource type you want to set, set to `all` if you want to show all your items by default + default_type: all +``` + +You can find a complete example [here](https://github.com/ilastik/bioimage-io-models/blob/master/collection.yaml). + +If you want to join as a community partner, please send the link to BioImage.IO by following the instructions for [joining community partners](https://github.com/bioimage-io/bioimage.io/blob/master/docs/community_partners/how_to_join.md). + +### How to contribute tests summaries + +As BioImage.IO community partner may contribute test summaries. As defined in [bioimageio.core](https://github.com/bioimage-io/core-bioimage-io-python/blob/d435fcdb38c8b2152ac0d20f61ee498d88e7f1d0/bioimageio/core/common.py#L4) a test summary is a dictionary with the following keys: + - name: str + - source_name: str + - status: Literal["passed", "failed"] + - error: Union[None, str] + - traceback: Optional[List[str]] + - nested_errors: Optional[Dict[str, dict]] + - bioimageio_spec_version: str + - bioimageio_core_version: str + - warnings: dict + +In the [BioImage.IO collection template](https://github.com/bioimage-io/collection-bioimage-io/blob/main/collection_rdf_template.yaml), where a community partner is registered, the location of `test_summaries` and how to trigger them can be specified as well. +The location of partner test summaries is specified by a GitHub repository `repository`, where test summaries are hosted in `deploy_branch`/`deploy_folder`. +To update the test summaries (for new or updated resources) `workflow` specifies a GitHub Actions workflow to trigger from `workflow_ref` by @bioimageiobot. +For the automatic trigger machanism to work the partner `repository` needs to invite @bioimageiobot as a collaborator and the `workflow` needs to run on `workflow_dispatch` with a `pending_matrix` input. + +Let's take a look at an example: the [ilastik partner entry](https://github.com/bioimage-io/collection-bioimage-io/blob/aa4742d33394809e44e63ce48f9bac9ad3518122/collection_rdf_template.yaml#L63-L68 +) below specifies that test summaries are hosted at [ilastik/bioimage-io-resources/tree/gh-pages/test_summaries](https://github.com/ilastik/bioimage-io-resources/tree/gh-pages/test_summaries). +The [test_bioimageio_resources.yaml](https://github.com/ilastik/bioimage-io-resources/blob/main/.github/workflows/test_bioimageio_resources.yaml) is regularly dispatched by @bioimageiobot to keep test summaries up-to-date. + +```yaml +id: ilastik +repository: ilastik/bioimage-io-resources +branch: main +collection_file_name: collection.yaml +test_summaries: + repository: ilastik/bioimage-io-resources + deploy_branch: gh-pages + deploy_folder: test_summaries + workflow: test_bioimageio_resources.yaml + workflow_ref: refs/heads/main +``` + +The test summaries are expected to follow the folder/file name pattern "//test_summary_*.yaml", where * can be any string to differentiate different test settings. + +#### Display of partner test summaries + +Once a community partner is registered to contribute test summaries with the `test_summaries` data explained above, the main [BioImage.IO CI](https://github.com/bioimage-io/collection-bioimage-io/blob/main/.github/workflows/auto_update_main.yaml) collects these summaries. The collection including these collected test summaries are displayed on bioimage.io. Currently test summaries are rendered like so: +![image](https://user-images.githubusercontent.com/15139589/226955477-6f8a8917-423f-4b9e-b08a-17bdb276aa2c.png) + + +#### Updating test summaries + +The main [BioImage.IO CI](https://github.com/bioimage-io/collection-bioimage-io/blob/main/.github/workflows/auto_update_main.yaml) triggers the partner's CI for new or updated resources. +Additionally, the parter may decide at any time to rerun (some of) their tests if changes on their side (like a new version release of their software) requires additional tests or a reevaluation. \ No newline at end of file diff --git a/docs/guides/community_partners_guide/README.md b/docs/guides/community_partners_guide/README.md new file mode 100644 index 00000000..2fb58ec7 --- /dev/null +++ b/docs/guides/community_partners_guide/README.md @@ -0,0 +1,348 @@ +# Community Partners Guide +BioImage.IO is a community-driven open source initiative, providing access to trained deep learning models and related resources contributed by the community members. To help us better disseminate and maintain the resources, we introduced the concepts of **community partner**. + +## Introduction to Community Partners + +### What is a community partner? +Usually, a community partner is an organization, a company, a research group, or a software team (of one or more) that can consume and/or produce resources of the BioImage.Io model zoo. Additionally, most partners continuously and openly contribute resources of their own. The first community partners represent open source consumer software of BioImage.IO (e.g. ilastik, Fiji, deepImageJ, ZeroCostDL4Mic, StarDist). + +### Benefits as a community partner +By joining BioImage.IO as a community partner, you will be able to: + - Participate in decision making process of the model specification. + - Show your logo in BioImage.IO and enable filtering models by compatibility with your software. + - Connect CI to automatically test new model compatibility with your software and use other infrastructure features provided by BioImage.IO. + +### Responsibilities +The main responsibilities of a community partner are: + - Use BioImage.IO as their only primary trained model repository. + - Review resources contributed by others that claim to be compatible with this community partner software. + - Maintain this community partner's models and other resources in their linked repository, setup continous integration workflows to test models and keep them up-to-date with the latest spec. + +### Who should join as a community partner? + * A team behind a software which produces or consumes trained models compatible with the BioImage.IO spec. + * A organization, group, company or team (of one or more) who contributed and will keep contributing more models to BioImage.IO. + +### How does it work? +Community partners can host their own Github repository for storing models and other resources that are relevant. These resources are listed in a [collection RDF](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/collection_spec_latest.md)–a yaml file–which will be dynamically linked to the [central repository of BioImage.IO](https://github.com/bioimage-io/bioimage-io-models). The [continuous integration (CI) service](https://github.com/bioimage-io/bioimage-io-models/actions) configured in the central repo will then pull the resources from partners' repo and compile them into items displayed in the BioImage.IO website. Each community partner is responsible for maintaining the resources that are relevant. + +![bioimage-io-community-partners](bioimage-io-community-partners.png) + +## Meet our Community Partners +Below is a list of our esteemed Community Partners who actively engage with the BioImage Model Zoo project, contributing their expertise, resources, and support to enhance the bioimage analysis community. + + +```html + +{ + "name": "BioImageIO Community Partners", + "type": "window", + "tags": [], + "ui": "", + "version": "0.1.0", + "cover": "", + "description": "Create a table for the bioimage.io community partners", + "icon": "extension", + "inputs": null, + "outputs": null, + "api_version": "0.1.8", + "env": "", + "permissions": [], + "requirements": ["https://cdnjs.cloudflare.com/ajax/libs/react/17.0.2/umd/react.production.min.js", "https://cdnjs.cloudflare.com/ajax/libs/react-dom/17.0.2/umd/react-dom.production.min.js", "https://cdnjs.cloudflare.com/ajax/libs/babel-standalone/6.26.0/babel.min.js", "https://cdn.tailwindcss.com"], + "dependencies": [], + "defaults": {"w": 20, "h": 10} +} + + + +// Main React App Component +const App = () => { + const [partners, setPartners] = React.useState([]); + + // Fetch JSON data from the URL + React.useEffect(() => { + fetch('https://raw.githubusercontent.com/bioimage-io/collection-bioimage-io/gh-pages/collection.json') + .then(response => response.json()) + .then(data => { + if (data.config && data.config.partners) { + setPartners(data.config.partners); + } else { + setPartners([]); + } + }) + .catch(err => console.error(err)); + }, []); + + return ( +
+
+

Community Partners

+ + + + + + + + + + {partners.map((partner, index) => ( + + + + + + ))} + +
Community PartnerDocumentationContact
{partner.name || 'N/A'}{partner.docs || 'N/A'} + {partner.contact ? ( + partner.contact.map((contact, i) => ( +
+
Name: {contact.name || 'N/A'}
+
Github: {contact.github || 'N/A'}
+
Email: {contact.email || 'N/A'}
+
+ )) + ) : ( + 'N/A' + )} +
+
+
+ ); +}; + +// Render the App component +ReactDOM.render(, document.getElementById('root')); + + + + + +
+ + + +``` + + +## How to join as a community partner? + +Note that in order to contribute resources to the BioImage.IO Model Zoo you do not need to become a community partner. How to contribute resources is described [here](/contribute_models/README.md). The role of a community partner is described [here](/community_partners/README.md). + + +If you are eligible and willing to join as a community partner, please submit a request issue [here](https://github.com/bioimage-io/collection-bioimage-io/issues/new) with relevant information including the following: +1. Description of your software, organization, company or team. +2. Description of the resources that you plan to contribute. Please also include the url to your project repo. +3. Description of future plans on how your project will be maintained. + +The admin team of BioImage.IO will discuss the request and decide whether to approve or decline. We will mainly check whether the project are beneficial for the users of BioImage.IO and the requirements for participation are met. + +Upon approval, we will guide you to follow these steps in order to incorporate your contribution to BioImage.IO: + +1. Firstly, please create or choose a GitHub repo for hosting your resource collection that you would like to contribute. We recommend to create a dedicated repository in your organization for this purpose. As an example you might want to take a look at the [ilastik collection](https://github.com/ilastik/bioimage-io-resources/blob/main/collection.yaml). +1. Add a [collection RDF](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/collection_spec_latest.md) in your chosen repository, which lists all resources you would like to contribute. For this, you will also need to prepare the icons of your software or project. +1. Setup CI service for testing your collection RDF. Please refer to [how to setup CI service](/community_partners/how_to_join?id=how-to-setup-ci-service-for-a-community-partners39-repo). +1. Make a PR (or an issue) in the BioImage.IO Collection repo to link your collection to the [collection_rdf_template.yaml](https://github.com/bioimage-io/collection-bioimage-io/blob/main/collection_rdf_template.yaml)(under `config.partners`). We only require the link to your collection RDF here and need to agree on a partner id for you. +1. To make the maintainance easier, we also ask you to add one of the admin member as collabrators in your resource collection repository. This will make it easier for us to help you maintaining your collection, and keep synchronized in case we make changes to the specification. + +## How to register a software or application? + +A community partner can have one or multiple associated software, you can register them in the collection RDF file of your repository (see the previous section about creating a collection repository). A software is categorized as "Application" in the BioImage Model Zoo. The first thing to do is to create an application file in the [ImJoy plugin file format](https://imjoy.io/docs/#/development?id=plugin-file-format). This basically allows you define a landing page for your software with executable features such as download or test run buttons for your software. The most common use case is to create a landing page for your software. Each software will have an unique id, typically in the format of `/`. Every model can add links (manually when upload or automatically via the CI) to the software. For each model, the user can click the link on top of the model card, and the landing page will be loaded. Through the ImJoy plugin mechanism, the context information contains the current model information will be injected to the landing page, it's up to the developer who made the software app to decided how to use those information. + +To see an example, you can find the [source for the ilastik app](https://github.com/ilastik/bioimage-io-resources/blob/main/src/ilastik-app.imjoy.html) and also the corresponding entry in the collection file [here](https://github.com/ilastik/bioimage-io-resources/blob/2d2f1b12b185b1b880bfb679ed2aa981bf88d1ed/collection.yaml#L45-L59). + +## How to setup CI service for a community partners' repo? + +The CI service is an useful tool to autotomize the maintenance of the model repo and ensure a high quality for all BioImage.IO resources. +You basically need to add some testing scripts to your repo and configure it using CI services such as Github Actions, Travis or Circle CI etc. The testing script will be triggered by a new commit or pull request to the repo. For simplicity, we recommend Github Actions which can be triggered by adding a yaml file under the folder `.github/workflows`. For example, here is an example file [.github/workflows/compile-manifest.yml](https://github.com/deepimagej/models/blob/master/.github/workflows/compile-manifest.yml) that we used to verify the model spec in the central repo. + +There are at least three steps are recommended: + 1. Run the [`compile_model_manifest.py`](https://github.com/bioimage-io/bioimage-io-models/blob/master/manifest.bioimage.io.yaml) script to make sure the manifest can be correctly compiled. + 2. Verify the yaml files according to model spec with [.github.com/bioimage-io/python-bioimage-io](https://github.com/bioimage-io/python-bioimage-io). + 3. If possible, test every models added to the repo. + +As a start, you can use [.github/workflows/compile-manifest.yml](https://github.com/deepimagej/models/blob/master/.github/workflows/compile-manifest.yml) as your template. + +See more information here: https://github.com/bioimage-io/collection-bioimage-io#contribute-resource-test-summaries + + +## Report User Analytics + +We provide the analytics service to help consumer software to keep track of their resource (including model, datasets etc.) downloads. + +### Report resource downloads + +To help us maintain the resource download statistics at BioImage.IO, please send a report to our analytics service when a resource item is downloaded. + +Under the hood, we use [matomo](https://matomo.org) to track the user downloads. It provide tracking api in various programming languages and frameworks, see here: https://developer.matomo.org/api-reference/tracking-api. + +The easiest way to report a model download is to send an http request to matomo. + + +You need to construct an URL to report the download: + +`https://bioimage.matomo.cloud/matomo.php?download=https://doi.org/[MODEL DOI]&idsite=1&rec=1&r=646242&h=13&m=35&s=20&url=http://bioimage.io/#/?id=[MODEL DOI]&uadata={"brands":[{"brand":"[CONSUMER ID]","version":"[CONSUMER VERSION]"}]}` + + +In the above URL, you need to provide the following parameters: + * `[MODEL DOI]`: The resource doi, it should be similar to `10.5281/zenodo.55555555`. Also note that Zenodo deposit has concept doi and version doi, we recommend to use the concept doi such that the downloads across versions can be aggregated. + * `[CONSUMER ID]`: The id for the registered consumer software, for example: `ilastik` or `deepimagej`. + * `[CONSUMER VERSION]`: The software version for the consumer software. + + +### Obtain resource usage statistics +You can get the user statistics from via the HTTP API, for example: + * To get the global statistics of the whole website: `https://bioimage.matomo.cloud/?module=API&method=Live.getCounters&idSite=1&lastMinutes=30&format=JSON&token_auth=anonymous` + * To get the number of downloads: `https://bioimage.matomo.cloud/?module=API&method=Actions.getDownloads&idSite=1&period=year&date=2023-03-01&format=JSON&token_auth=anonymous` + * To get the number of downloads for a specific resource (via DOI): ```https://bioimage.matomo.cloud/?module=API&method=Actions.getDownload&downloadUrl=https://doi.org/`[MODEL DOI]`&idSite=1&period=year&date=2023-03-01&format=JSON&token_auth=anonymous```. To see an example, click here: https://bioimage.matomo.cloud/?module=API&method=Actions.getDownload&downloadUrl=https://doi.org/test&idSite=1&idCustomReport=1&period=year&date=2023-03-01&format=JSON&token_auth=anonymous + + For more detailed API, see here: https://developer.matomo.org/api-reference/reporting-api + + +Please note that the reports are not processed in realtime, this means you won't see the statistics for your reports immediately: + - In the report request, we need to configure the date properly. For example, we can change period to `year` and date to `2023-03-01` (see here: https://developer.matomo.org/api-reference/Piwik/Period) + - The report will only be generated every 15 minutes: https://matomo.org/faq/general/faq_41/ so we won't see the report immediately. + +## BioImage.IO Partner Collection + +A BioImage.IO partner collection is a YAML file in GitHub repository of a community partner. The file adheres to the collection RDF specification described [here](https://github.com/bioimage-io/spec-bioimage-io#collection-resource-description-file-specification). + +The appearance of the partner collection on the website can be customized by the `config` field as described in the next section. + +### Customizing appearance on bioimage.io + +Like any RDF, a collection RDF may have a `config` field to hold non-standardized metadata. We currently use some of this metadata to customize the partner collection appearance on the bioimage.io website. The fields used here are subject to change, but as a community partner we'll keep you in the loop on any changes here and will likely formalize this part in the future. + +A typical partner collection RDF `config` field may look like this: + +```yaml +config: + # a url for the user to get more details about the collection or your project + # it can be a markdown file (*.md) hosted on github, you need to use the `raw` url + # or an external link to your website + about_url: http://details_about_my_collection + + # these tags will be used to filter items when the user select this collection + tags: + - awesome + + # the logo for the collection, you can use an emoji or a url to a png/jpg/gif/svg image + logo: 🦒 + + # the icon for your collection you can use an emoji or a url to a png/jpg/gif/svg image + # note, this must be a square or contained in a square + icon: 🦒 + + + # settings for the splash screen + splash_title: Awesome Collection + splash_subtitle: Awesome Collection is Awesome! + splash_feature_list: + - Easy to use... + - It's just awesome... + explore_button_text: Start Awesomeness + background_image: static/img/zoo-background.svg + + # the available resource types in your collection + resource_types: + - model + - application + - notebook + - dataset + + # the default resource type you want to set, set to `all` if you want to show all your items by default + default_type: all +``` + +You can find a complete example [here](https://github.com/ilastik/bioimage-io-models/blob/master/collection.yaml). + +If you want to join as a community partner, please send the link to BioImage.IO by following the instructions for [joining community partners](https://github.com/bioimage-io/bioimage.io/blob/master/docs/community_partners/how_to_join.md). + +## How to contribute tests summaries + +As BioImage.IO community partner may contribute test summaries. As defined in [bioimageio.core](https://github.com/bioimage-io/core-bioimage-io-python/blob/d435fcdb38c8b2152ac0d20f61ee498d88e7f1d0/bioimageio/core/common.py#L4) a test summary is a dictionary with the following keys: + - name: str + - source_name: str + - status: Literal["passed", "failed"] + - error: Union[None, str] + - traceback: Optional[List[str]] + - nested_errors: Optional[Dict[str, dict]] + - bioimageio_spec_version: str + - bioimageio_core_version: str + - warnings: dict + +In the [BioImage.IO collection template](https://github.com/bioimage-io/collection-bioimage-io/blob/main/collection_rdf_template.yaml), where a community partner is registered, the location of `test_summaries` and how to trigger them can be specified as well. +The location of partner test summaries is specified by a GitHub repository `repository`, where test summaries are hosted in `deploy_branch`/`deploy_folder`. +To update the test summaries (for new or updated resources) `workflow` specifies a GitHub Actions workflow to trigger from `workflow_ref` by @bioimageiobot. +For the automatic trigger machanism to work the partner `repository` needs to invite @bioimageiobot as a collaborator and the `workflow` needs to run on `workflow_dispatch` with a `pending_matrix` input. + +Let's take a look at an example: the [ilastik partner entry](https://github.com/bioimage-io/collection-bioimage-io/blob/aa4742d33394809e44e63ce48f9bac9ad3518122/collection_rdf_template.yaml#L63-L68 +) below specifies that test summaries are hosted at [ilastik/bioimage-io-resources/tree/gh-pages/test_summaries](https://github.com/ilastik/bioimage-io-resources/tree/gh-pages/test_summaries). +The [test_bioimageio_resources.yaml](https://github.com/ilastik/bioimage-io-resources/blob/main/.github/workflows/test_bioimageio_resources.yaml) is regularly dispatched by @bioimageiobot to keep test summaries up-to-date. + +```yaml +id: ilastik +repository: ilastik/bioimage-io-resources +branch: main +collection_file_name: collection.yaml +test_summaries: + repository: ilastik/bioimage-io-resources + deploy_branch: gh-pages + deploy_folder: test_summaries + workflow: test_bioimageio_resources.yaml + workflow_ref: refs/heads/main +``` + +The test summaries are expected to follow the folder/file name pattern "//test_summary_*.yaml", where * can be any string to differentiate different test settings. + +### Display of partner test summaries + +Once a community partner is registered to contribute test summaries with the `test_summaries` data explained above, the main [BioImage.IO CI](https://github.com/bioimage-io/collection-bioimage-io/blob/main/.github/workflows/auto_update_main.yaml) collects these summaries. The collection including these collected test summaries are displayed on bioimage.io. Currently test summaries are rendered like so: +![image](https://user-images.githubusercontent.com/15139589/226955477-6f8a8917-423f-4b9e-b08a-17bdb276aa2c.png) + + +### Updating test summaries + +The main [BioImage.IO CI](https://github.com/bioimage-io/collection-bioimage-io/blob/main/.github/workflows/auto_update_main.yaml) triggers the partner's CI for new or updated resources. +Additionally, the parter may decide at any time to rerun (some of) their tests if changes on their side (like a new version release of their software) requires additional tests or a reevaluation. diff --git a/docs/community_partners/bioimage-io-community-partners.png b/docs/guides/community_partners_guide/bioimage-io-community-partners.png similarity index 100% rename from docs/community_partners/bioimage-io-community-partners.png rename to docs/guides/community_partners_guide/bioimage-io-community-partners.png diff --git a/docs/contribute_models/contribute_model.png b/docs/guides/contribute_model.png similarity index 100% rename from docs/contribute_models/contribute_model.png rename to docs/guides/contribute_model.png diff --git a/docs/guides/developer_guide.md b/docs/guides/developer_guide.md new file mode 100644 index 00000000..4c867a4f --- /dev/null +++ b/docs/guides/developer_guide.md @@ -0,0 +1,129 @@ +# Developer Guide + +## Models in the BioImage Model Zoo +A BioImage.IO model is a zip file containing all the items, technical description and metadata of the model, together with the trained architecture of the model. Briefly, a BioImage.IO model has at least, the following items: +* Trained model in the correct format (check the Resource Description File Specifications for the [supported formats](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/user_docs/model_descr_latest.md)) +* Example input image (numpy array) +* Example output (numpy array) +* Resource description file specifications (`rdf.yaml`) +* An example cover image for visual representation of the model in the zoo. + +In some cases, the model may need additional files. + +### Model contribution requirements + +- Follow the [BioImage.IO Model Resource Description File Specification (RDF)](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/user_docs/model_descr_latest.md) with `format_version>= 0.4.5`. +- The model is expected to be cross-compatible among the consumer software, and should always run on at least one. +- The model should be well documented (i.e., human readable name and rich description tailored for life-scientists, citations) +- The model should be public and can be used by anyone under the chosen licensing conditions. + +### Upload a model to the BioImage Model Zoo + +**1. Create a BioImage.IO model** +Two options: + 1. Choose one way to create your model: + - Automatic export of the model using the [bioimageio.core python library](https://github.com/bioimage-io/core-bioimage-io-python) (recomended). + Example code [here](https://github.com/bioimage-io/core-bioimage-io-python/blob/main/example/model_creation.ipynb). + - The main function to build the model is `bioimageio.core.build_model`. Check its input variables to know what has to be provided. + - Manual generation of the model: + - Create the [BioImage.IO Model Resource Description File Specifications](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/user_docs/model_descr_latest.md) (`rdf.yaml` file). + - Each field on the file is either mandatory or optional. In the Bioimage Model Zoo web page you can find different examples. + 2. Check that the model is correctly created: + - Static validation of the model format using the [bioimageio.core python library](https://github.com/bioimage-io/core-bioimage-io-python) library (*e.g.*, in the terminal, `bioimageio validate /../rdf.yaml`). + - Dynamic validation of the model's deployment (*e.g.*, in the terminal, `bioimageio test-model --weights tensorflow_saved_model_bundle --device cpu /.../rdf.yaml`). It tests that the model generates the expected output. + +**2. Upload the model to the BioImage Model Zoo** + +To upload a model to the BioImage Model Zoo, you have a tutorial video of the process step by step available [here](https://oc.embl.de/index.php/s/JBWwJGgsXh0vYM6). + + + +For a detailed explanation, follow these steps: + 1. In [BioImage.IO](https://bioimage.io/), click on `+Upload` and follow the steps: + + 2. Log in to Zenodo and give access to the BioEngine application. You will see an automatic message once you are logged in. If not, refresh the page. This step needs to be done only for the first time you upload a model. + + 3. Upload your model RDF. + + + 4. Complete the missing fields. + + + + + 5. A [Pull Request (PR)](https://github.com/bioimage-io/collection-bioimage-io/pulls/bioimageiobot) is generated (this process may take some minutes). In the PR, the model is tested by a Continuous Integration (CI) workflow for its technical correctness. and reviewed by a maintainer from the BioImage.IO team. This PR is aimed for further discussions between model contributors and the BioImage.IO team. + + 6. Once the model passes all checks and has the approval of a maintainer, it will be added to the BioImage.IO collection and displayed in the webpage (this process may take some minutes). + +### Upload a model through Zenodo +**Note:** This tutorial provides a temporary solution for uploading models to the BioImage Model Zoo via Zenodo while the upload feature on the BioImage.IO website is being fixed. + +This tutorial will guide you through the process of uploading a model to the BioImage Model Zoo community on Zenodo. The BioImage Model Zoo project aims to collect and share bioimage analysis models, and your contribution is valuable. Follow the steps below to upload your model. + +1. Open your web browser and navigate to the Zenodo website at [https://zenodo.org/](https://zenodo.org). You need to create a Zenodo account if you do not have one. + + Zenodo initial page + +2. On the right, close to your username, click the "New upload" button to begin the model upload process. Make sure that the repository is set as public. +The files in the BioImage.IO zip have to be uploaded one-by-one (See the example in the image below). Note that you can drag & drop all together at once. + + New upload + +3. Add `bioimage.io` on Keywords and subjects. This is crucial for us to identify your submission. + + Find BioImage.IO community + +4. Follow the on-screen instructions to provide the required information about your model. Make sure to include a clear description, relevant tags, and any necessary documentation. + +5. Once finished, click on Submit. + +6. Your model will be proposed as a new contribution to the BioImage Model Zoo automatically. If the model passes all the tests, it will be automatically displayed in the Zoo. If the model does not pass the test, the GitHub users indicated in `maintainers` in the `rdf.yaml` file will be noitified through GitHub. This process can take 12-24h. + +You've successfully uploaded your model to the BioImage Model Zoo community on Zenodo. Thank you for your contribution to the BioImage Model Zoo project. Remember that this is a temporary solution while the upload feature on the BioImage.IO website is being fixed. We appreciate your patience and support! + + +### Model Documentation +#### Model naming + +Models are expected to be used by life-scientists, thus, it is expected that the naming is human readable but also informative enough regarding the final application and the biological tissue being analysed. Example: + + **Name:** `Neuron Segmentation in EM (Membrane Prediction)`, `B. Sutilist bacteria segmentation - Widefield microscopy - 2D UNet` + + +#### Model Tags +The tags in the model RDF are used to search for each model in the BioImage Model Zoo. The more informative tags you write, the easier it will be for a potential user to find your model. Example: + + **My model description**: An encoder-decoder trained for denoising of point-scanning super-resolution microsocpy images of HeLa cells microtubules + + **Tags**: `denoising`, `PSSR`, `microtubules`, `encoder-decoder`, `deblurring`, `fluorescence`, `2D`, `HeLa cells`, `deepimagej`, `ilastik`, `image restoration`, `trained-model` etc. + +#### Model links +The BioImage Model Zoo is a software webpage. Each model is displayed with an interactive card that can have datasets, notebooks, applications, consumer-software or test-run buttons linked. Example: + + **Links**: `imjoy/BioImageIO-Packager`, `ilastik/ilastik`, `deepimagej/deepimagej`, `zero/dataset_fnet_3d_zerocostdl4mic` etc. + +#### Representative Covers + +You can include different cover images that represent the analysed tissue, imaging modality, image processing task and the performance of the model. This image will be used in the model card to guide the users through the model search. + + +### Considerations for the model description file + +When following the BioImage.IO model RDF specification provided at https://github.com/bioimage-io/spec-bioimage-io, it is important that you pay special attention to the following: +* Choose test input image(s) and generate the respective test output tensor(s). This enables our scripts to test your model for technical correctness and to test which [consumer software](https://bioimage.io/docs/#/consumer_software/model_runner) can process it. +* Pre-processing and post-processing should be always described. You can check which [preprocessing](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/preprocessing_spec_latest.md) and [postprocessing](https://github.com/bioimage-io/spec-bioimage-io/blob/gh-pages/postprocessing_spec_latest.md) functions are supported at the moment and open an [issue here](https://github.com/bioimage-io/spec-bioimage-io/issues) if you are missing a specific operation. +* Do not forget to include any additional files needed for the correct execution of the model during the upload process. + +## Other contributions +You are welcome to submit your **models**, **datasest**, **applicaitons** and Jupyter **notebooks** to BioImage.IO. + +To add an resource item to BioImage.IO, you need to provide a set of basic information about the resouce, including name, description, authors etc. and we will generate a resource card to display in the website. + +For Community Partners, you can add models directly to the linked repository. If you are not part of the community partners, you can follow the instructions below to submit resource items (models, datasets etc.) to BioImage.IO. + +### Submit to BioImage.IO +* Step 1, prepare a [`Resource Description File`](/bioimageio_rdf_spec)(RDF) and complete at least the mandatory fields and ideally also the recommended fields for different types of resource. + +* Step 2, save the RDF file in one of the public git hosting website, it is recommended to store the RDF file in your project git repository on Github/Gitlab/Bitbucket (make sure it's a public repo). Alternatively, you can post it on [Gist](https://gist.github.com/), copy the the **raw** url to the actual file content. + +* Step 3, post the url to the comment box below (if you don't see it, click [here](https://github.com/bioimage-io/bioimage-io-models/issues/26)). And the admin team will check and verify the format and incooperate to BioImage.IO if the submitted file is qualified. \ No newline at end of file diff --git a/docs/user_guide/download_model_packager.jpg b/docs/guides/download_model_packager.jpg similarity index 100% rename from docs/user_guide/download_model_packager.jpg rename to docs/guides/download_model_packager.jpg diff --git a/docs/user_guide/fiji_bioimage_predict.jpg b/docs/guides/fiji_bioimage_predict.jpg similarity index 100% rename from docs/user_guide/fiji_bioimage_predict.jpg rename to docs/guides/fiji_bioimage_predict.jpg diff --git a/docs/contribute_models/upload_1.png b/docs/guides/upload_1.png similarity index 100% rename from docs/contribute_models/upload_1.png rename to docs/guides/upload_1.png diff --git a/docs/contribute_models/upload_2.png b/docs/guides/upload_2.png similarity index 100% rename from docs/contribute_models/upload_2.png rename to docs/guides/upload_2.png diff --git a/docs/contribute_models/upload_3.png b/docs/guides/upload_3.png similarity index 100% rename from docs/contribute_models/upload_3.png rename to docs/guides/upload_3.png diff --git a/docs/guides/user_guide.md b/docs/guides/user_guide.md new file mode 100644 index 00000000..d5246664 --- /dev/null +++ b/docs/guides/user_guide.md @@ -0,0 +1,70 @@ +# User Guide +This guide is intended for users wanting to consume or use models from the BioImage Model Zoo. There are plenty of models in the BioImage Model Zoo that you can use in your own software, in the software of our community partners or you can even download them and use them in a notebook or code of your own. + +## Downloading and using Models from the BioImage Model Zoo + +See a [video](https://oc.embl.de/index.php/s/eJOIdzDVJpToETd) about using a model from the BioImage Model Zoo in different software. + +bioimage.io download + + +## Using BioImage Model Zoo models in different software + +### BiaPy +TBD + +### DeepImageJ + +**Note: deepImageJ supports PyTorch and Tensorflow 1 models** + +1. Install the [deepImageJ plugin](https://deepimagej.github.io/download.html) in ImageJ. +This will give you all the necessary Plugins to run bioimage.io models at the moment. + +2. Install a model from the [BioImage Model Zoo](https://bioimage.io/): + 1) Download a deepImageJ model from the BioImage Model Zoo repository. + 2) Use `DeepImageJ Install Model` in ImageJ to install the `.zip` file that you just downloaded: choose the `Private model` option and `From ZIP file`. + 3) In the `zip` file you just downloaded, there is an `exampleImage.tif`that you can open in ImageJ and process with the model you just downloaded. + 4) See a detailed tutorial [here](https://deepimagej.github.io/tutorials.html). + + +### Fiji +**Note: Fiji only supports Tensorflow 1 models at the moment!** + +1. Install the [CSBDeep-Plugin](https://github.com/CSBDeep/CSBDeep_website/wiki/CSBDeep-in-Fiji-%E2%80%93-Installation) in Fiji. +This will give you all the necessary Plugins to run bioimage.io models at the moment. +2. Open the image you want to run the model on +3. a) If your model is a [CSBDeep](https://imagej.net/CSBDeep) one, go to Plugins > CSBDeep and choose either "N2V", "DenoiSeg" or "Run your network"(default) + + b) For any other bioimage.io model, go to Plugins > bioimage.io > bioimage.io prediction. +4. Continuing from 3b) you will arrive at this window: + +Fiji bioimage.io prediction + +The configuration fields should be self-explanatory. + +5. Click "OK" to run the model prediction. + + +### Ilastik +TBD + +### ImJoy +TBD + + +### ZeroCostDL4Mic +**Note: [ZeroCostDL4Mic](https://github.com/HenriquesLab/ZeroCostDL4Mic/wiki) allows you trainig models and upload them to the BioImage Model Zoo or fine-tune existing ones!** + +1. Download a ZeroCostDL4Mic model from the [BioImage Model Zoo](https://bioimage.io/) repository. +2. Unzip the model `.zip` file so you can use it later in the notebook. +3. Open the ZeroCostDL4Mic notebook that corresponds to the model you downloaded. +4. When required, specify the path to the unziped folder containing the model. + +## Best Practices for Model Usage +TBD + +## Use Cases +- [Use-case 1: Stardist H&E nucleus segmentation](https://github.com/bioimage-io/use-cases/tree/main/case1-stardist) +- [Use-case 2: 3D U-Net for cell-segmentation in light microscopy](https://github.com/bioimage-io/use-cases/tree/main/case2-finetuning) +- [Use-case 3: Classification, imjoy & python library usage](https://github.com/bioimage-io/use-cases/tree/main/case3-devtools) +- [Use-case 4: Domain adaptation for mitochondria segmentation in EM](https://github.com/bioimage-io/use-cases/tree/main/case4-research) \ No newline at end of file diff --git a/docs/contribute_models/zenodo_upload_01.png b/docs/guides/zenodo_upload_01.png similarity index 100% rename from docs/contribute_models/zenodo_upload_01.png rename to docs/guides/zenodo_upload_01.png diff --git a/docs/contribute_models/zenodo_upload_03.png b/docs/guides/zenodo_upload_03.png similarity index 100% rename from docs/contribute_models/zenodo_upload_03.png rename to docs/guides/zenodo_upload_03.png diff --git a/docs/contribute_models/zenodo_upload_04.png b/docs/guides/zenodo_upload_04.png similarity index 100% rename from docs/contribute_models/zenodo_upload_04.png rename to docs/guides/zenodo_upload_04.png diff --git a/docs/help_desk/README.md b/docs/help_desk/README.md new file mode 100644 index 00000000..b60502d8 --- /dev/null +++ b/docs/help_desk/README.md @@ -0,0 +1,64 @@ +# Help Desk + +## Glossary +In the ever-evolving field of bioimage analysis, understanding the terminology is essential. Explore our glossary to familiarize yourself with key terms and concepts used throughout the BioImage Model Zoo project. + +| Term | Definition | +| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Community Partner** | Usually, a community partner is an organization, a company, a research group, or a software team (of one or more) that can consume and/or produce resources of the BioImage Model Zoo. Additionally, most partners continuously and openly contribute resources of their own. The founders community partners represent open source consumer software of [BioImage.IO](http://BioImage.IO/) (e.g. [ilastik](https://www.ilastik.org), [Fiji](https://imagej.net/software/fiji/), [deepImageJ](https://deepimagej.github.io), [ZeroCostDL4Mic](https://github.com/HenriquesLab/ZeroCostDL4Mic), [StarDist](https://github.com/stardist/stardist)). A Community Partner can either be a team behind a software which produces or consumes trained models compatible with the [BioImage.IO](http://bioimage.io/) spec or an organization, group, company or team (of one or more) who contributed and will keep contributing more models to BioImage Model Zoo. | +| **Consumer** | Refers to an individual or user who engages with the project by utilizing the pre-existing models available on [BioImage.IO](http://bioimage.io/). Their primary role involves downloading these models and incorporating them into their workflow using compatible software or any specific manner that suits their needs. For example, a Life Scientist can be considered a consumer by accessing the[BioImage.IO](http://bioimage.io/), selecting a Deep Learning model relevant to their research, and integrating it into their preferred software, such as deepImageJ or other compatible platforms. As a consumer, their focus lies in leveraging the existing models to enhance their bioimage analysis tasks, thereby benefiting from the diverse range of models provided by the BioImage Model Zoo. | +| **Contributor** | A contributor can either be an individual person or a group, entity, or software. As an individual contributor, your primary objective is to actively contribute to the project by uploading models to BioImage Model Zoo. By doing so, you expand the range of available models, enriching the repository and fostering the growth of the bioimage analysis community. As a contributor, you play a crucial role in sharing your expertise and innovative models with the broader community, contributing to advancements in bioimage analysis. Similarly, a software contributor refers to a software application or system that actively participates in the project by uploading models to [BioImage.IO](http://bioimage.io/). These software contributors enhance the available models by providing new and diverse solutions, further expanding the capabilities of the BioImage Model Zoo. Whether you contribute as an individual or a software entity, your active involvement in uploading models to [BioImage.IO](http://bioimage.io/) is instrumental in supporting the project's objectives. By sharing your models, you contribute to the collective knowledge and empower researchers in the bioimage analysis field. | +| **Consumer Software** | A consumer software refers to any software application or tool that utilizes the models from the BioImage Model Zoo repository. Consumer software is designed to interact with and make use of the pretrained AI models available in the BioImage Model Zoo. A consumer software is any software application or tool that utilize pretrained AI models for bioimage analysis tasks, either through integration, execution, or interaction with the models available in the BioImage Model Zoo. | +| **Model Resource Description File Specifications (RDF YAML)** | The Model Resource Description File (RDF) specifications refer to a set of guidelines that define the structure and content of a YAML file used to describe the AI models with pretrained weights in a standardized format. The model RDF serves as a metadata file that provides essential information about the model, its properties, and its intended use. The RDF file contains both mandatory and optional fields that capture relevant details about the model, such as its architecture, input/output formats, preprocessing steps, and performance metrics. By following the Model RDF specifications, developers and researchers can create consistent and interoperable descriptions of their AI models, allowing seamless integration and sharing within the [BioImage.IO](http://bioimage.io/) ecosystem. | + +## FAQs + +Have questions about how to participate, contribute, or engage with the BioImage Model Zoo? Check out our Frequently Asked Questions (FAQs) for detailed answers and insights into making the most of your experience with our project. + +**How can I participate in the BioImage Model Zoo?** +To participate, you can take on the role of a **Community Partner** or engage as a **Consumer** or **Contributor** of models from the BioImage Model Zoo. + +- **Consumer**: As a Consumer, your role involves utilizing the existing models available on bioimage.io by downloading and incorporating them into your workflow using connected software or in any specific manner. For instance, a Life Scientist can be a Consumer by using a Deep Learning model downloaded from bioimage.io and integrating it into any compatible software (deepImageJ, Ilastik, ImJoy, ZeroCostDL4Mic, ...). + +- **Contributor**: If your primary objective is to contribute models to bioimage.io, then you are a Contributor. As such, you play a crucial role in expanding the range of available models and supporting the bioimage analysis community. + +**What is a Community Partner? Who can be a Community Partner?** + +Usually, a **Community Partner** is an organization, a company, a research group, or a software team (of one or more) that can consume and/or produce models from/for the BioImage.IO Model Zoo. + +The first community partners represent open source consumer software of BioImage.IO (e.g. ilastik, Fiji, deepImageJ, ZeroCostDL4Mic, StarDist). + +A Community Partner can either be a team behind a software which produces or consumes trained models compatible with the BioImage.IO specifications or an organization, group, company, or team (of one or more) who contributes models to BioImage.IO. + + +**How can I upload a model to the BioImage Model Zoo?** + +To contribute a model to the BioImage Model Zoo, please refer to the [Contribute Models section](https://bioimage.io/docs/#/contribute_models/README). This section provides detailed instructions on how to upload a model, including the necessary steps and required files for your contribution. + +**How can I report issues or provide feedback regarding models on BioImage.IO?** + +If you encounter a bug or wish to share feedback, please use our [GitHub issues page](https://github.com/bioimage-io/bioimage.io/issues). We appreciate your input and kindly request that you ensure your feedback is not duplicated. Your contributions help improve the BioImage Model Zoo for the entire community. + +**What is AI4Life?*** + +AI4Life is a project whose goal is to provide sustainable, intuitive, and highest quality research services and infrastructures that will enable all life scientists to exploit machine learning to improve the utility and interpretability of image data, the key to future biomedical research. + +**How is AI4Life related to the BioImage Model Zoo?** + +AI4Life is a project closely aligned with the BioImage Model Zoo. It plays a significant role in supporting and enhancing the BioImage Model Zoo's mission and initiatives. + +**Can I use models from the BioImage Model Zoo for commercial purposes?** +Yes, you are welcome to use the models from the BioImage Model Zoo for commercial purposes. However, we kindly request that you provide appropriate credits when using these models as a gesture of acknowledgment for the contributions of the model creators and the BioImage Model Zoo community. + +## Code of Conduct +The code of conducte of the BioImage Model Zoo can be visited here: [Code of Conduct](/CODE_OF_CONDUCT.md) + +## Contact us + +If you can't find what you're looking for, there are several ways to communicate with us or get assistance. Here are some options: + +- You can write an issue in our [GitHub repository](https://github.com/bioimage-io/bioimage-io/issues). + +- You can ask a question or post in the [Image.sc Forum](https://forum.image.sc) using the tag 'bioimageio'. This way, not only our team but also others facing similar issues can benefit from your post. + +- Alternatively, you can contact us through our [contact form](https://oeway.typeform.com/to/K3j2tJt7), and someone will be available to assist with your questions. \ No newline at end of file diff --git a/docs/terms_of_service.md b/docs/terms_of_service.md index 0ba032cc..7842fdb8 100644 --- a/docs/terms_of_service.md +++ b/docs/terms_of_service.md @@ -1,6 +1,6 @@ # Terms of Service Agreement -Welcome to BioImage.io! Our website, https://bioimage.io (the "Site") is owned and operated by the AI4Life consortium ("AI4Life"). By accessing or using the Site and related services (collectively, the "Services"), you ("you" or "User") agree to be legally bound by the following terms and conditions ("Terms of Service" or "Terms"). +Welcome to BioImage.IO! Our website, https://bioimage.io (the "Site") is owned and operated by the AI4Life consortium ("AI4Life"). By accessing or using the Site and related services (collectively, the "Services"), you ("you" or "User") agree to be legally bound by the following terms and conditions ("Terms of Service" or "Terms"). If you disagree with these Terms, you must not use the Site or Services. Please read these Terms carefully before using the Site or Services. diff --git a/docs/tools_and_resources/README.md b/docs/tools_and_resources/README.md new file mode 100644 index 00000000..9169ebe8 --- /dev/null +++ b/docs/tools_and_resources/README.md @@ -0,0 +1,79 @@ +# Tools and Resources +In this part of the documentation different tools and resources and its documentation can be found. + +* **[DL4MicEverywhere](tools_and_resources/dl4miceverywhere.md)**: DL4MicEverywhere is a platform that offers researchers an easy-to-use gateway to cutting-edge deep learning techniques for bioimage analysis. It features interactive Jupyter notebooks with user-friendly graphical interfaces that require no coding skills. The platform utilizes Docker containers to ensure portability and reproducibility, guaranteeing smooth operation across various computing environments. +* **[BioImage.IO Chatbot](tools_and_resources/bioimageiochatbot.md)**: The BioImage.IO Chatbot is a versatile conversational agent designed to assist users in accessing information related to bioimage analysis. It leverages the power of Large Language Models (LLMs) and integrates user-specific data to provide contextually accurate and personalized responses. Whether you're a researcher, developer, or scientist, the chatbot is here to make your bioimage analysis journey smoother and more informative. +* **[Python BioImage.IO Core Package](tools_and_resources/bioimageio-core-package.md)**: Learn how to leverage the Python BioImage.IO Core Package, an essential toolkit for integrating and using bioimaging models and datasets in Python environments. +* **[Java Deep Learning Library](tools_and_resources/jdll.md)**: Explore the capabilities of the Java Deep Learning Library (JDLL), a comprehensive Java-based library designed for building and deploying deep learning models in bioimaging. +* **[BioEngine](tools_and_resources/bioengine.md)**: Initially designed to support the BioImage Model Zoo (https://bioimage.io) for effortless model testing, BioEngine empowers both experts and newcomers in the field of bioimage analysis. This cloud-based infrastructure brings AI to the next level by offering a user-friendly, plug-and-play cloud solution that not only simplifies model testing but also pioneers next-generation bioimage analysis capabilities. + +## DL4MicEverywhere +TBD + +## BioImage.IO Chatbot +TBD + +## Python BioImage.IO Core Package +TBD + +## Java Deep Learning Library +TBD + +## BioEngine +### Building BioEngine Apps +We use BioEngine, a tailored version of [ImJoy](https://imjoy.io) to run models applications. Therefore, you can basically run ImJoy plugins with the BioEngine specific api. + +Depending on different types of application, for web application, please refer to [here](https://github.com/imjoy-team/imjoy-core#use-your-web-application-inside-imjoy) for integrating the `imjoy-rpc` with your web app. Once done you can simply set `source` in the [`Resource Description File`](/bioimageio_rdf_spec) to your web app url. + + +For Jupyter notebooks and other types, you will need to build a new ImJoy plugin. + +By default it loads also a [Jupyter Engine](https://github.com/imjoy-team/jupyter-engine-manager) which uses free computational resources on MyBinder.org, so you can also run small models in Python. + +For example, this is a basic ImJoy plugin in Python, that works with the BioEngine: + +```python +from imjoy import api + +class ImJoyPlugin(): + def setup(self): + pass + + def run(self, ctx): + # when the app is triggered from a model/dataset/notebook etc. + # you will receive the current item via `ctx.data` + if ctx.config.mode == 'one': + model = ctx.data + assert model.type == 'model' + api.alert("Running app from model: " + model['name']) + + # when the app is triggered from the app card it self + # you will receive all the resource items via `ctx.data` + elif ctx.config.mode == 'all': + all_items = ctx.data + # filter the models based on type + models = filter(lambda it: it['type'] == 'model', all_items) + api.alert("Number of models: " + str(len(models))) + +api.export(ImJoyPlugin()) +``` + +For other types of plugins (e.g. in Javascript), the same `ctx` object will be passed into the plugin. + +You can do the debugging inside [ImJoy](https://imjoy.io), for more information, please consult https://imjoy.io/docs. + +To test with the BioEngine, you can go to https://bioimage.io, on the menu located in the top-right corner, you can load a local ImJoy plugin file to run it with the BioEngine. One additional feature is that the BioEngine will keep track of the local file, if you made new changes with your code editor (e.g. vim, vscode) the engine will try to reload the plugin file. + +TIP: if your imjoy plugin is designed for not only work with bioimage.io but also other purposes, you can use an `if` statement to check `ctx.config.type == 'bioengine'`. + +### Make a standalone web app compatible with ImJoy/BioEngine + +Making an ImJoy plugin is not the only way to support the BioEngine, if you have already a web application or website, you can easily load a `imjoy-rpc` js file to your website and expose api for ImJoy/BioEngine. + +See [here](https://github.com/imjoy-team/ImJoy-core#use-your-web-application-inside-imjoy) for more details. + +For example, [Kaibu](https://kaibu.org) is a standlone web app that compatible with the BioEngine. Because it [loads the imjoy-rpc library](https://github.com/imjoy-team/kaibu/blob/efd355eff95da9aa0f7eb97103585b753063c05d/public/index.html#L45) and [exposed api functions for ImJoy](https://github.com/imjoy-team/kaibu/blob/master/src/imjoyAPI.js). + +### How to submit BioEngine Apps to the website? + +If you are one of our [community partners](https://github.com/bioimage-io/bioimage.io/blob/master/docs/join-partners.md), you can add the app url to your model repository. Otherwise, please submit your BioEngine Apps to BioImage.IO by posting the url [here](https://github.com/bioimage-io/bioimage-io-models/issues/26). diff --git a/docs/bioengine/tutorials.md b/docs/tools_and_resources/bioengine.md similarity index 100% rename from docs/bioengine/tutorials.md rename to docs/tools_and_resources/bioengine.md diff --git a/docs/tools_and_resources/bioimageiochatbot.md b/docs/tools_and_resources/bioimageiochatbot.md new file mode 100644 index 00000000..cdd64b44 --- /dev/null +++ b/docs/tools_and_resources/bioimageiochatbot.md @@ -0,0 +1,2 @@ +# BioImage.IO Chatbot +In progress... \ No newline at end of file diff --git a/docs/tools_and_resources/dl4miceverywhere.md b/docs/tools_and_resources/dl4miceverywhere.md new file mode 100644 index 00000000..888cb38f --- /dev/null +++ b/docs/tools_and_resources/dl4miceverywhere.md @@ -0,0 +1,2 @@ +# DL4MicEverywhere +In progress... \ No newline at end of file diff --git a/docs/tools_and_resources/jdll.md b/docs/tools_and_resources/jdll.md new file mode 100644 index 00000000..11f7dd6f --- /dev/null +++ b/docs/tools_and_resources/jdll.md @@ -0,0 +1,2 @@ +# Java Deep Learning Library (JDLL) +In progress... \ No newline at end of file diff --git a/public/manifest.json b/public/manifest.json index ae53bb34..ad10f19f 100755 --- a/public/manifest.json +++ b/public/manifest.json @@ -1,6 +1,6 @@ { - "name": "Bioimage.io", - "short_name": "Bioimage.io", + "name": "BioImage.IO", + "short_name": "BioImage.IO", "theme_color": "#7957d5", "background_color": "#ffffff", "display": "standalone", diff --git a/site.config.json b/site.config.json index ffd34082..be2dc522 100644 --- a/site.config.json +++ b/site.config.json @@ -4,7 +4,7 @@ "site_logo": "/static/img/bioimage-io-logo-white.svg", "author": "BioImage.IO Team", "keywords": "Bioimaging, AI, deep learning, image processing", - "description": "Bioimage.io -- an AI model repository for deep learning.", + "description": "BioImage.IO -- an AI model repository for deep learning.", "twitter_site": "@bioimageio", "twitter_creator": "@weioyang", "twitter_image": "https://bioimage.io/static/img/bioimage-io-banner.png",