From 674166dd2e091b8ee26d38dbcfa1b9904760b9b9 Mon Sep 17 00:00:00 2001 From: Jesse Mapel <jam826@nau.edu> Date: Wed, 20 Feb 2019 10:17:13 -0700 Subject: [PATCH] Updated README (#154) * Updated README * Added BAE license and removed open source license --- LICENSE | 24 -------- README.md | 154 ++++++++++++++++++++-------------------------------- license.txt | 11 ++++ 3 files changed, 71 insertions(+), 118 deletions(-) delete mode 100644 LICENSE create mode 100644 license.txt diff --git a/LICENSE b/LICENSE deleted file mode 100644 index cf1ab25..0000000 --- a/LICENSE +++ /dev/null @@ -1,24 +0,0 @@ -This is free and unencumbered software released into the public domain. - -Anyone is free to copy, modify, publish, use, compile, sell, or -distribute this software, either in source code form or as a compiled -binary, for any purpose, commercial or non-commercial, and by any -means. - -In jurisdictions that recognize copyright laws, the author or authors -of this software dedicate any and all copyright interest in the -software to the public domain. We make this dedication for the benefit -of the public at large and to the detriment of our heirs and -successors. We intend this dedication to be an overt act of -relinquishment in perpetuity of all present and future rights to this -software under copyright law. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR -OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -OTHER DEALINGS IN THE SOFTWARE. - -For more information, please refer to <http://unlicense.org> diff --git a/README.md b/README.md index 9f4d5c6..473f62d 100644 --- a/README.md +++ b/README.md @@ -1,100 +1,66 @@ # CSM-CameraModel -ISD Specification: https://github.com/USGS-Astrogeology/pfeffernusse/blob/master/swagger.yaml - -## Setting up dependencies with conda (RECOMMENDED) - -Install conda if you do not already have it. -```bash -wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh; -bash miniconda.sh -b -``` -> You can add a `-p <install-prefix>` to choose where to install miniconda. By default, it will install it to `$HOME/miniconda3`. - -### Setting up conda for bash -Copy and paste the following into a terminal running the `bash` shell: -```bash -echo -e "\n\n# Adding miniconda3 to PATH" >> $HOME/.bashrc && \ -echo -e "export PATH=$HOME/miniconda3/bin:\$PATH" >> $HOME/.bashrc && \ -source $HOME/.bashrc && \ -which conda -``` -> *For more information: [bash installation](https://conda.io/docs/user-guide/install/linux.html "Reference to bash conda install")* - -### Setting up conda for tcsh -Copy and paste the following into a terminal running the `tcsh` shell: -```tcsh -echo "\n\n# Setting up miniconda3 for tcsh" >> $HOME/.cshrc && \ -echo "source $HOME/miniconda3/etc/profile.d/conda.csh > /dev/null" >> $HOME/.cshrc && \ -source $HOME/.cshrc && \ -which conda -``` -> *For more information: [tcsh installation](https://github.com/ESMValGroup/ESMValTool/issues/301 "Reference to tcsh conda install")* - -### Creating an isolated conda environment -Run the following commands to create a self-contained dev environment for CSM-CameraModel (type `y` to confirm creation): -```bash -conda create -n csmdev -c usgs-astrogeology cmake libcsm -``` -> *For more information: [conda environments](https://conda.io/docs/user-guide/tasks/manage-environments.html)* - -### Activating the environment -After creating the `csmdev` environment and installing cmake and libcsm into it, we need to activate it. Right now, cmake, libcsm, and their dependencies are isolated to a conda environment and we need to tell conda that we want to use it. The activation command depends on your shell. -* **bash**: `source activate csmdev` -* **tcsh**: `conda activate csmdev` -> *You can add these to the end of your $HOME/.bashrc or $HOME/.cshrc if you want the `csmdev` environment to be active in every new terminal.* +Community Sensor Model (CSM) compliant sensor models created by USGS Astrogeology +Science Center. -## Building CSM-CameraModel -After you've set up conda, you can build CSM-CameraModel: - -1. Fork `USGS-Astrogeology/CSM-CameraModel` if you don't already have a fork. -2. Clone your fork of `CSM-CameraModel` *with `--recursive` option to get the gtest submodule*. -```bash -git clone --recursive git@github.com:<your-username>/CSM-CameraModel.git -cd CSM-CameraModel -git remote add upstream git@github.com:USGS-Astrogeology/CSM-CameraModel.git -``` -3. Sync your fork with `upstream` and ensure the gtest submodule is init'd if your fork is old. -```bash -git pull upstream master -git submodule update --init --recursive -git push -u origin master -``` -4. `mkdir build && cd build` -5. `cmake .. && make` -6. `ctest` +CSM-CameraModel contains two different sensor models. The first, is a generic +framing camera model written from scratch. The second is a generic line scan +camera model based on code from BAE Systems Information and Electronic Systems +Integration Inc. + +## Using CSM-CameraModel + +This library is a CSM plugin library that is intended to be dynamically loaded +at run time along side the +[CSM API library](https://github.com/USGS-Astrogeology/csm). + +Once, the library is loaded, it can be accessed through the CSM Plugin interface. +For an example of how to do through the CSM c++ interface see the SensorModelFactory +class in [SensorUtils](https://github.com/USGS-Astrogeology/SensorUtils). +For an example of how to do this through the CSM Python bindings see this +[notebook](http://nbviewer.jupyter.org/gist/thareUSGS/4c0eb72799edc33ff4816b2587027148). + +From the CSM Plugin interface, a generic framing camera model +(USGS_ASTRO_FRAME_SENSOR_MODEL) or generic line scan camera model +(USGS_ASTRO_LINE_SCANNER_SENSOR_MODEL) can be instantiated from suitable Image +Support Data (ISD). Under the CSM standard, each plugin library can define its +own ISD format. This library uses an auxiliary JSON formatted file that must be +next to the image file passed to the CSM::ISD class. We provide an OpenAPI +server for generating these, +[pfeffernusse](https://github.com/USGS-Astrogeology/pfeffernusse). The swagger +specification is located on +[swaggerhub](https://app.swaggerhub.com/apis/USGS-Astro/pfeffernusse2/0.1.4-oas3). --- -## Building without a package manager -To build: - -1. Install [libcsmapi](https://github.com/sminster/csm "CSM API") - > You can install this with an `INSTDIR` of your choice, or let it default (see [libcsmapi README](https://github.com/sminster/csm/blob/master/README)) -```bash -mkdir $HOME/csmenv -cd $HOME -git clone git@github.com:sminster/csm.git -cd csm -make -f Makefile.linux64 all install clean INSTDIR="$csmenv" -``` -2. Install cmake >= 3.10 -```bash -cd $HOME -wget https://cmake.org/files/v3.12/cmake-3.12.0-Linux-x86_64.tar.gz -tar xzf cmake-3.12.0-Linux-x86_64.tar.gz -rsync -azv cmake-3.12.0-Linux-x86_64/ $HOME/csmenv/ -echo -e "\n#Prepending csm env to path\nsetenv PATH "$HOME/csmenv/bin:$PATH" >> $HOME/.cshrc -source $HOME/.cshrc -``` -3. Fork and clone down this repo and its submodules (gtest) -```bash -git clone --recursive git@github.com:<username>/CSM-CameraModel.git -cd CSM-CameraModel -git remote add upstream git@github.com:USGS-Astrogeology/CSM-CameraModel.git -git pull upstream master -git submodule update --init --recursive -git push -u origin master -``` -4. `mkdir build` && `cd build` -5. `cmake -DCSM_INCLUDE_DIR="${csmenv}/include/csm -DCSM_LIBRARY="${csmenv}/lib/libcsmapi.so .. && make` +## Build Requirements + +* cmake 3.10 or newer +* GNU-compatible Make +* a c++11 compliant compiler + +This repository has all of its external c++ dependencies included in it. The +excellent header-only JSON library +[JSON for Modern C++](https://github.com/nlohmann/json) is included directly in +the source code. The other two dependencies, the CSM API library, and gtest +are included as git submodules. When you clone this library make sure you add +the `--recursive` flag to your `git clone` command. Alaterntively, you can run +`git submodule update --init --recursive` after cloning. The library can also be +compiled against an installed versions of the CSM API by setting the BUILD_CSM +flag to OFF during cmake configuration. + +## Building CSM-CameraModel + +CSM-CameraModel uses a standard cmake build system. To compile the library, and +tests use the following commands: + +1. `mkdir build && cd build` +2. `cmake .. && cmake --build .` + +## Testing CSM-CameraModel + +All of the tests for CSM-CameraModel are written in the googletests framework +and are run via ctest. To run all of the tests simply run `ctest` in the build. + +All of the tests are purposefully written to use generic data that values have +been hand validated for. This data can be found under `tests/data`. diff --git a/license.txt b/license.txt new file mode 100644 index 0000000..756adf6 --- /dev/null +++ b/license.txt @@ -0,0 +1,11 @@ +Copyright © 2017 BAE Systems Information and Electronic Systems Integration Inc. + +Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: + +1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -- GitLab