Merge pull request #179 from CosmiQ/dev

Version 0.1.0 release

.readthedocs-environment.yml

@@ -0,0 +1,8 @@
+name: solaris
+dependencies:
+  - python
+  - pip
+  - gdal
+  - pip:
+    - sphinx_bootstrap_theme
+    - nbsphinx

.readthedocs.yml

@@ -0,0 +1,17 @@
+version: 2
+formats:
+  - htmlzip
+
+python:
+  version: 3.6
+  install:
+    - method: pip
+      path: .
+    - requirements: .rtfd-requirements.txt
+
+
+conda:
+  environment: .readthedocs-environment.yml
+
+build:
+  image: latest

.rtfd-requirements.txt

@@ -0,0 +1 @@
+sphinx_bootstrap_theme

README.md

@@ -13,30 +13,58 @@
 <a href="https://codecov.io/gh/CosmiQ/solaris"><img align="center" src="https://codecov.io/gh/CosmiQ/solaris/branch/master/graph/badge.svg" /></a>
 </p>
 
-## This package is under active development. Check back soon for updates!
+## This is a beta version of Solaris which may continue to develop. Please report any bugs through issues!
 
+- [Documentation](#documentation)
 - [Installation Instructions](#installation-instructions)
 - [Dependencies](#dependencies)
 - [License](#license)
 ---
+
 This repository provides the source code for the CosmiQ Works `solaris` project, which provides software tools for:
 - Tiling large-format overhead images and vector labels
 - Converting between geospatial raster and vector formats and machine learning-compatible formats
 - Performing semantic and instance segmentation, object detection, and related tasks using deep learning models designed specifically for overhead image analysis
 - Evaluating performance of deep learning model predictions
 
+## Documentation
+The full documentation for `solaris` can be found at https://solaris.readthedocs.io, and includes:
+- A summary of `solaris`
+- Installation instructions
+- API Documentation
+- Tutorials for common uses
+
+The documentation is still being improved, so if a tutorial you need isn't there yet, check back soon or post an issue!
+
 ## Installation Instructions
+
+_coming soon_: One-command installation from conda-forge.
+
 We recommend creating a `conda` environment with the dependencies defined in [environment.yml](./environment.yml) before installing `solaris`. After cloning the repository:
 ```
 cd solaris
+```
+
+If you're installing on a system with GPU access:
+```
+conda env create -n solaris -f environment-gpu.yml
+```
+Otherwise:
+If you're installing on a system with GPU access:
+```
 conda env create -n solaris -f environment.yml
+```
+
+Finally, regardless of your installation environment:
+```
 conda activate solaris
 pip install .
 ```
 
 #### pip
 
-The package also exists on[ PyPI](https://pypi.org), but note that some of the dependencies, specifically [rtree](https://github.com/Toblerity/) and [gdal](https://www.gdal.org), are challenging to install without anaconda. We therefore recommend installing at least those dependencies using `conda` before installing from PyPI.
+
+The package also exists on[ PyPI](https://pypi.org), but note that some of the dependencies, specifically [rtree](https://github.com/Toblerity/rtree) and [gdal](https://www.gdal.org), are challenging to install without anaconda. We therefore recommend installing at least those dependency using `conda` before installing from PyPI.
 
 ```
 conda install -c conda-forge rtree gdal=2.4.1
@@ -60,7 +88,7 @@ docker pull cosmiqworks/solaris
 See the [readthedocs](https://cw-eval.readthedocs.io/) page. -->
 
 ## Dependencies
-All dependencies can be found in the docker file [Dockerfile](./Dockerfile) or
+All dependencies can be found in the requirements file [./requirements.txt](requirements.txt) or
 [environment.yml](./environment.yml)
 
 ## License

docker/cpu/Dockerfile

@@ -0,0 +1,79 @@
+FROM nvidia/cuda:9.2-devel-ubuntu16.04
+LABEL maintainer="nweir <nweir@iqt.org>"
+
+ARG solaris_branch='master'
+
+
+# prep apt-get and cudnn
+RUN apt-get update && apt-get install -y --no-install-recommends \
+	    apt-utils \
+    rm -rf /var/lib/apt/lists/*
+
+# install requirements
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends \
+    bc \
+    bzip2 \
+    ca-certificates \
+    curl \
+    git \
+    libgdal-dev \
+    libssl-dev \
+    libffi-dev \
+		libncurses-dev \
+    libgl1 \
+    jq \
+    nfs-common \
+    parallel \
+    python-dev \
+    python-pip \
+    python-wheel \
+    python-setuptools \
+    unzip \
+		vim \
+    wget \
+    build-essential \
+  && apt-get clean \
+  && rm -rf /var/lib/apt/lists/*
+
+SHELL ["/bin/bash", "-c"]
+ENV PATH /opt/conda/bin:$PATH
+
+# install anaconda
+RUN wget --quiet https://repo.anaconda.com/miniconda/Miniconda3-4.5.4-Linux-x86_64.sh -O ~/miniconda.sh && \
+    /bin/bash ~/miniconda.sh -b -p /opt/conda && \
+    rm ~/miniconda.sh && \
+    /opt/conda/bin/conda clean -tipsy && \
+    ln -s /opt/conda/etc/profile.d/conda.sh /etc/profile.d/conda.sh && \
+    echo ". /opt/conda/etc/profile.d/conda.sh" >> ~/.bashrc && \
+    echo "conda activate base" >> ~/.bashrc
+
+# prepend pytorch and conda-forge before default channel
+RUN conda update conda && \
+    conda config --prepend channels conda-forge && \
+    conda config --prepend channels pytorch
+
+# get dev version of solaris and create conda environment based on its env file
+WORKDIR /tmp/
+RUN git clone https://github.com/cosmiq/solaris.git && \
+    cd solaris && \
+    git checkout ${solaris_branch} && \
+    conda env create -f environment.yml
+ENV PATH /opt/conda/envs/solaris/bin:$PATH
+
+RUN cd solaris && pip install .
+
+# install various conda dependencies into the space_base environment
+RUN conda install -n solaris \
+                     jupyter \
+                     jupyterlab \
+                     ipykernel
+
+# add a jupyter kernel for the conda environment in case it's wanted
+RUN source activate solaris && python -m ipykernel.kernelspec \
+    --name solaris --display-name solaris
+
+# open ports for jupyterlab and tensorboard
+EXPOSE 8888 6006
+
+RUN ["/bin/bash"]

docker/Dockerfile → docker/gpu/Dockerfile

@@ -63,7 +63,7 @@ WORKDIR /tmp/
 RUN git clone https://github.com/cosmiq/solaris.git && \
     cd solaris && \
     git checkout ${solaris_branch} && \
-    conda env create -f environment.yml
+    conda env create -f environment-gpu.yml
 ENV PATH /opt/conda/envs/solaris/bin:$PATH
 
 RUN cd solaris && pip install .

docs/_static/custom_styles.css

@@ -0,0 +1,15 @@
+p {
+  font-size: 1.1em;
+}
+
+h1 {
+  font-size: 2.5em;
+}
+
+h2 {
+  font-size: 2.2em;
+}
+
+h3 {
+  font-size: 1.75em;
+}

docs/_templates/autosummary/base.rst

@@ -0,0 +1,5 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/_templates/autosummary/class.rst

@@ -0,0 +1,29 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: Methods
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Attributes
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/autosummary/module.rst

@@ -0,0 +1,36 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: Functions
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: Classes
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: Exceptions
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/base/base.rst

@@ -0,0 +1,7 @@
+.. {{ obj.type }}:: {{ obj.name }}
+
+	{% if summary %}
+
+	{{ obj.summary }}
+
+	{% endif %}

docs/_templates/dotnet/base_detail.rst

@@ -0,0 +1,88 @@
+{% block title %}
+
+{{ obj.short_name }} {{ obj.type.title()}}
+{{ "=" * (obj.short_name|length + obj.type|length + 1) }}
+
+{% endblock %}
+
+{% block summary %}
+  {% if obj.summary %}
+
+{{ obj.summary }}
+
+  {% endif %}
+{% endblock %}
+
+{% if obj.namespace %}
+Namespace
+    :dn:ns:`{{ obj.namespace }}`
+
+{% endif %}
+{% if obj.assemblies %}
+Assemblies
+  {% for assembly in obj.assemblies %}
+    * {{ assembly }}
+  {% endfor %}
+{% endif %}
+
+----
+
+.. contents::
+   :local:
+
+{% block inheritance %}
+
+{% if obj.inheritance %}
+
+Inheritance Hierarchy
+---------------------
+
+{% for item in obj.inheritance %}
+* :dn:{{ item.ref_directive }}:`{{ item.ref_name }}`
+    {% endfor %}
+* :dn:{{ obj.ref_directive }}:`{{ obj.ref_name }}`
+{% endif %}
+
+{% endblock %}
+
+{% block syntax %}
+
+{% if obj.example %}
+
+Syntax
+------
+
+.. code-block:: csharp
+
+    {{ obj.example|indent(4) }}
+
+{% endif %}
+
+{% endblock %}
+
+
+{% block content %}
+
+.. dn:{{ obj.ref_type }}:: {{ obj.definition }}
+    :hidden:
+
+.. dn:{{ obj.ref_type }}:: {{ obj.name }}
+
+{% for item_type in obj.item_map.keys() %}
+{% if item_type in obj.item_map %}
+
+{{ item_type.title() }}
+{{ "-" * item_type|length }}
+
+.. dn:{{ obj.ref_type }}:: {{ obj.name }}
+    :noindex:
+    :hidden:
+
+    {% for obj_item in obj.item_map.get(item_type, []) %}
+    {{ obj_item.render()|indent(4) }}
+    {% endfor %}
+
+{% endif %}
+{% endfor %}
+
+{% endblock %}