Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Use more concise cross-referencing syntax in docs #1809

Merged
merged 1 commit into from Jun 23, 2023
Merged

Use more concise cross-referencing syntax in docs #1809

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
20 changes: 8 additions & 12 deletions docs/framework/architecture.rst
View file
Open in desktop
Expand Up @@ -46,9 +46,7 @@ The full source code for Examples 1 and 2 is in `rastervision.pipeline_example_p
Example 1: a simple pipeline
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. currentmodule:: rastervision.pipeline

A :class:`~pipeline.Pipeline` in Raster Vision is a class which represents a sequence of commands with a shared configuration in the form of a :class:`~pipeline_config.PipelineConfig`. Here is a toy example of these two classes that saves a set of messages to disk, and then prints them all out.
A :class:`.Pipeline` in Raster Vision is a class which represents a sequence of commands with a shared configuration in the form of a :class:`.PipelineConfig`. Here is a toy example of these two classes that saves a set of messages to disk, and then prints them all out.

.. literalinclude:: /../rastervision_pipeline/rastervision/pipeline_example_plugin1/sample_pipeline.py
:language: python
Expand Down Expand Up @@ -153,7 +151,7 @@ We can run the pipeline as follows:
hola bob!!!
hola susan!!!

The output in ``/opt/data/sample-pipeline`` contains a ``pipeline-config.json`` file which is the serialized version of the ``SamplePipeline2Config`` created in ``config3.py``. The serialized configuration is used to transmit the configuration when running a pipeline remotely. It also is a programming language-independent record of the fully-instantiated configuration that was generated by the ``run`` command in conjunction with any command line arguments. Below is the partial contents of this file. The interesting thing to note here is the ``type_hint`` field that appears twice. This is what allows the JSON to be deserialized back into the Python classes that were originally used.(Recall that the ``register_config`` decorator is what tells the ``Registry`` the type hint for each :class:`~config.Config` class.)
The output in ``/opt/data/sample-pipeline`` contains a ``pipeline-config.json`` file which is the serialized version of the ``SamplePipeline2Config`` created in ``config3.py``. The serialized configuration is used to transmit the configuration when running a pipeline remotely. It also is a programming language-independent record of the fully-instantiated configuration that was generated by the ``run`` command in conjunction with any command line arguments. Below is the partial contents of this file. The interesting thing to note here is the ``type_hint`` field that appears twice. This is what allows the JSON to be deserialized back into the Python classes that were originally used. (Recall that the ``register_config`` decorator is what tells the :class:`.Registry` the type hint for each :class:`.Config` class.)

.. code-block:: json

Expand Down Expand Up @@ -190,11 +188,9 @@ However, sometimes you will need to modify the functionality of Raster Vision to

General information about plugins can be found in :ref:`bootstrap` and :ref:`pipelines plugins`. The following are some brief pointers on how to write plugins for different scenarios. In the future, we would like to enhance this section.

.. currentmodule:: rastervision.pipeline

* To add commands to an existing :class:`~pipeline.Pipeline`: write a plugin with subclasses of the :class:`~pipeline.Pipeline` and its corresponding :class:`~pipeline_config.PipelineConfig` class. The new :class:`~pipeline.Pipeline` should add a method for the new command, and modify the list of ``commands``. Any new configuration should be added to the subclass of the :class:`~pipeline_config.PipelineConfig`. Example: running some data pre- or post-processing code in a pipeline.
* To modify commands of an existing :class:`~pipeline.Pipeline`: same as above except you will override command methods. If a new configuration field is required, you can subclass the :class:`~config.Config` class that field resides within. Example: custom chipping functionality for semantic segmentation. You will need to create subclasses of :class:`~rastervision.core.rv_pipeline.semantic_segmentation_config.SemanticSegmentationChipOptions`, :class:`~rastervision.core.rv_pipeline.semantic_segmentation.SemanticSegmentation`, and :class:`~rastervision.core.rv_pipeline.semantic_segmentation_config.SemanticSegmentationConfig`.
* To create a substantially new :class:`~pipeline.Pipeline`: write a new plugin that adds a new :class:`~pipeline.Pipeline`. See the :mod:`rastervision.core` plugin, in particular, the contents of the :mod:`rastervision.core.rv_pipeline` package. If you want to add a new geospatial deep learning pipeline (eg. for chip regression), you may want to override the :mod:`rastervision.core.rv_pipeline` class. In other cases that deviate more from :class:`~rastervision.core.rv_pipeline.Raster VisionPipeline`, you may want to write a new :class:`~pipeline.Pipeline` class with arbitrary commands and logic, but that uses the core model building and training functionality in the :mod:`rastervision.pytorch_learner` plugin.
* To add the ability to use new file systems or run in new cloud environments: write a plugin that adds a new :class:`~file_system.file_system.FileSystem` or :class:`~runner.runner.Runner`. See the :mod:`rastervision.aws_s3` and :mod:`rastervision.aws_batch` plugins for examples.
* To use an existing :mod:`rastervision.core.rv_pipeline` with a new :class:`~rastervision.core.backend.backend.Backend`: write a plugin that adds a subclass of :class:`~rastervision.core.backend.backend.Backend` and :class:`~rastervision.core.backend.backend_config.BackendConfig`. See the :mod:`rastervision.pytorch_backend` plugin for an example.
* To override model building or training routines in an existing :class:`~rastervision.pytorch_backend.pytorch_learner_backend.PyTorchLearnerBackend`: write a plugin that adds a subclass of :class:`~rastervision.pytorch_learner.learner.Learner` (and :class:`~rastervision.pytorch_learner.learner_config.LearnerConfig`) that overrides :meth:`~rastervision.pytorch_learner.learner.Learner.build_model` and :meth:`~rastervision.pytorch_learner.learner.Learner.train_step`, and a subclass of :class:`~rastervision.pytorch_backend.pytorch_learner_backend.PyTorchLearnerBackend` (and :class:`~rastervision.pytorch_backend.pytorch_learner_backend_config.PyTorchLearnerBackendConfig`) that overrides the backend so it uses the :class:`~rastervision.pytorch_learner.learner.Learner` subclass.
* To add commands to an existing :class:`.Pipeline`: write a plugin with subclasses of the :class:`.Pipeline` and its corresponding :class:`.PipelineConfig` class. The new :class:`.Pipeline` should add a method for the new command, and modify the list of ``commands``. Any new configuration should be added to the subclass of the :class:`.PipelineConfig`. Example: running some data pre- or post-processing code in a pipeline.
* To modify commands of an existing :class:`.Pipeline`: same as above except you will override command methods. If a new configuration field is required, you can subclass the :class:`.Config` class that field resides within. Example: custom chipping functionality for semantic segmentation. You will need to create subclasses of :class:`.SemanticSegmentationChipOptions`, :class:`.SemanticSegmentation`, and :class:`.SemanticSegmentationConfig`.
* To create a substantially new :class:`.Pipeline`: write a new plugin that adds a new :class:`.Pipeline`. See the :mod:`rastervision.core` plugin, in particular, the contents of the :mod:`rastervision.core.rv_pipeline` package. If you want to add a new geospatial deep learning pipeline (eg. for chip regression), you may want to override the :mod:`rastervision.core.rv_pipeline` class. In other cases that deviate more from :class:`~rastervision.core.rv_pipeline.Raster VisionPipeline`, you may want to write a new :class:`.Pipeline` class with arbitrary commands and logic, but that uses the core model building and training functionality in the :mod:`rastervision.pytorch_learner` plugin.
* To add the ability to use new file systems or run in new cloud environments: write a plugin that adds a new :class:`.FileSystem` or :class:`.Runner`. See the :mod:`rastervision.aws_s3` and :mod:`rastervision.aws_batch` plugins for examples.
* To use an existing :mod:`rastervision.core.rv_pipeline` with a new :class:`.Backend`: write a plugin that adds a subclass of :class:`.Backend` and :class:`.BackendConfig`. See the :mod:`rastervision.pytorch_backend` plugin for an example.
* To override model building or training routines in an existing :class:`.PyTorchLearnerBackend`: write a plugin that adds a subclass of :class:`.Learner` (and :class:`.LearnerConfig`) that overrides :meth:`~rastervision.pytorch_learner.learner.Learner.build_model` and :meth:`~rastervision.pytorch_learner.learner.Learner.train_step`, and a subclass of :class:`.PyTorchLearnerBackend` (and :class:`.PyTorchLearnerBackendConfig`) that overrides the backend so it uses the :class:`.Learner` subclass.
8 changes: 4 additions & 4 deletions docs/framework/misc.rst
View file
Open in desktop
Expand Up @@ -6,14 +6,14 @@ Miscellaneous Topics
File Systems
------------

The :class:`~rastervision.pipeline.file_system.file_system.FileSystem` architecture supports multiple file systems through an interface that is chosen by URI. There is built-in support for: local and HTTP file systems in the :mod:`rastervision.pipeline` package, AWS S3 in the :mod:`rastervision.aws_s3` plugin, and any file that can be opened using GDAL VSI in the :mod:`rastervision.gdal_vsi` plugin. Some file systems support read only (HTTP), while others are read/write. If you need to support other file storage systems, you can add new :class:`~rastervision.pipeline.file_system.file_system.FileSystem` subclasses via a plugin.
The :class:`.FileSystem` architecture supports multiple file systems through an interface that is chosen by URI. There is built-in support for: local and HTTP file systems in the :mod:`rastervision.pipeline` package, AWS S3 in the :mod:`rastervision.aws_s3` plugin, and any file that can be opened using GDAL VSI in the :mod:`rastervision.gdal_vsi` plugin. Some file systems support read only (HTTP), while others are read/write. If you need to support other file storage systems, you can add new :class:`.FileSystem` subclasses via a plugin.

Viewing Tensorboard
-------------------

.. currentmodule:: rastervision.pytorch_backend.pytorch_learner_backend_config

The PyTorch backends included in the :mod:`rastervision.pytorch_backend` plugin will start an instance of TensorBoard while training if :attr:`log_tensorboard=True <PyTorchLearnerBackendConfig.log_tensorboard>` and :attr:`run_tensorboard=True <PyTorchLearnerBackendConfig.run_tensorboard>` in the :class:`~PyTorchLearnerBackendConfig`.
The PyTorch backends included in the :mod:`rastervision.pytorch_backend` plugin will start an instance of TensorBoard while training if :attr:`log_tensorboard=True <PyTorchLearnerBackendConfig.log_tensorboard>` and :attr:`run_tensorboard=True <PyTorchLearnerBackendConfig.run_tensorboard>` in the :class:`.PyTorchLearnerBackendConfig`.

To view TensorBoard, go to ``https://<domain>:6006/``. If you're running locally, then ``<domain>`` should be ``localhost``, and if you are running remotely (for example AWS), ``<domain>`` is the public DNS of the machine running the training command. If running locally, make sure to forward port 6006 using the ``--tensorboard`` option to ``docker/run`` if you are using it. At the moment, basic metrics are logged each epoch, but more interesting visualization could be added in the future.

Expand All @@ -22,7 +22,7 @@ Transfer learning using models trained by RV

.. currentmodule:: rastervision.pytorch_learner

To use a model trained by Raster Vision for transfer learning or fine tuning, you can use output of the TRAIN command of the experiment as a pretrained model of further experiments. The ``last-model.pth`` model file in the ``train`` directory can be used as a pretrained model in a new pipeline. To do so, set the :attr:`~learner_config.ModelConfig.init_weights` field to the model file in the :class:`~learner_config.ModelConfig` in the new pipeline.
To use a model trained by Raster Vision for transfer learning or fine tuning, you can use output of the TRAIN command of the experiment as a pretrained model of further experiments. The ``last-model.pth`` model file in the ``train`` directory can be used as a pretrained model in a new pipeline. To do so, set the :attr:`~learner_config.ModelConfig.init_weights` field to the model file in the :class:`.ModelConfig` in the new pipeline.

.. _model bundle:

Expand All @@ -31,7 +31,7 @@ Making Predictions with Model Bundles

.. currentmodule:: rastervision.core

To make predictions on new imagery, the :ref:`bundle <bundle command>` command generates a "model bundle" which can be used with the :ref:`predict cli command` command. This loads the model and saves the predictions for a single scene. If you need to call this for a large number of scenes, consider using the :class:`~predictor.Predictor` class programmatically, as this will allow you to load the model once and use it many times. This can matter a lot if you want the time-to-prediction to be as fast as possible - the model load time can be orders of magnitudes slower than the prediction time of a loaded model.
To make predictions on new imagery, the :ref:`bundle <bundle command>` command generates a "model bundle" which can be used with the :ref:`predict cli command` command. This loads the model and saves the predictions for a single scene. If you need to call this for a large number of scenes, consider using the :class:`.Predictor` class programmatically, as this will allow you to load the model once and use it many times. This can matter a lot if you want the time-to-prediction to be as fast as possible - the model load time can be orders of magnitudes slower than the prediction time of a loaded model.

The model bundle is a zip file containing the model weights and the configuration necessary for Raster Vision to use the model. This configuration includes the configuration of the model architecture, how the training data was processed by :mod:`RasterTransformers <rastervision.core.data.raster_transformer>` (if any), the subset of bands used by the :ref:`usage_raster_source`, and potentially other things. The model bundle holds all of this necessary information, so that a prediction call only needs to know what imagery it is predicting against.

Expand Down