Initial commit.

colour-science · Oct 16, 2023 · 796e10b · 796e10b
commit 796e10b
Show file tree

Hide file tree

Showing 45 changed files with 3,840 additions and 0 deletions.
diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml
@@ -0,0 +1,43 @@
+name: Bug Report
+description: Report an issue or a bug.
+title: "[BUG]: << Please use a comprehensive title... >>"
+labels: [ Defect ]
+
+body:
+  - type: markdown
+    attributes:
+      value: >
+        Thank you for taking the time to file a bug report. Before continuing, please take some time to check the existing [issues](https://github.com/colour-science/colour-visuals/issues).
+        The issue could already be fixed in the [develop](https://github.com/colour-science/colour-visuals) branch. If you have an installation problem, the [installation guide](https://www.colour-science.org/installation-guide/) describes the recommended process.
+
+  - type: textarea
+    attributes:
+      label: "Description"
+      description: >
+        Please describe the issue in a few short sentences.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: "Code for Reproduction"
+      description: >
+        If possible, please provide a minimum self-contained example reproducing the issue.
+      placeholder: |
+        << Your code here... >>
+      render: python
+
+  - type: textarea
+    attributes:
+      label: "Exception Message"
+      description: >
+        If any, please paste the *full* exception message.
+      placeholder: |
+        << Full traceback starting from `Traceback (most recent call last):`... >>
+      render: shell
+
+  - type: textarea
+    attributes:
+      label: "Environment Information"
+      description: If possible, please paste the output from `import colour; colour.utilities.describe_environment()`.
+      render: shell
diff --git a/.github/ISSUE_TEMPLATE/documentation-improvement.yml b/.github/ISSUE_TEMPLATE/documentation-improvement.yml
@@ -0,0 +1,40 @@
+name: Documentation Improvement
+description: Report a documentation improvement.
+title: "[DOCUMENTATION]: << Please use a comprehensive title... >>"
+labels: [ Documentation ]
+
+body:
+  - type: markdown
+    attributes:
+      value: >
+        Thank you for taking the time to file a documentation improvement report. Before continuing, please take some time to check the existing [issues](https://github.com/colour-science/colour-visuals/issues).
+
+  - type: input
+    attributes:
+      label: Documentation Link
+      description: >
+        Please link to any documentation or examples that you are referencing. Suggested improvements should be based on the [development version of the documentation](https://colour-visuals.readthedocs.io/en/develop/).
+      placeholder: >
+        << https://colour-visuals.readthedocs.io/en/develop/... >>
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Description
+      description: >
+        Please describe what is missing, unclear or incorrect.
+    validations:
+      required: true
+
+  - type: textarea
+    attributes:
+      label: Suggested Improvement
+      description: >
+        Please describe how the documentation could be improved.
+
+  - type: textarea
+    attributes:
+      label: "Environment Information"
+      description: If possible, please paste the output from `import colour; colour.utilities.describe_environment()`.
+      render: shell
diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml
@@ -0,0 +1,18 @@
+name: Feature Request
+description: Suggest a new feature to implement.
+title: "[FEATURE]: << Please use a comprehensive title... >>"
+labels: [ Feature ]
+
+body:
+  - type: markdown
+    attributes:
+      value: >
+        Thank you for taking the time to file a feature request. Before continuing, please take some time to check the existing [issues](https://github.com/colour-science/colour-visuals/issues) and also the [draft release notes](https://gist.github.com/KelSolaar/4a6ebe9ec3d389f0934b154fec8df51d).
+
+  - type: textarea
+    attributes:
+      label: "Description"
+      description: >
+        Please describe the new feature in a few short sentences.
+    validations:
+      required: true
diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml
@@ -0,0 +1,17 @@
+name: Question
+description: Ask a question.
+title: "[DISCUSSION]: << Please use a comprehensive title... >>"
+labels: [ Discussion ]
+
+body:
+  - type: markdown
+    attributes:
+      value: Thank you for taking the time to ask a question or discuss. Before continuing, we would be glad if you were to start this discussion in the dedicated [discussions](https://github.com/colour-science/colour-visuals/discussions) area.
+
+  - type: textarea
+    attributes:
+      label: "Question"
+      description: >
+        If you are still here, please consider using the dedicated [discussions](https://github.com/colour-science/colour-visuals/discussions) area.
+      placeholder: >
+        << The discussions area is this way: https://github.com/colour-science/colour-visuals/discussions...  >>
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,31 @@
+<!--
+Thank you for taking the time to create this pull request. If it is the first
+time you are contributing to a colour-science repository, a contributing guide
+is available to guide the process: https://www.colour-science.org/contributing/.
+-->
+
+# Summary
+
+<!-- Please write a summary describing the changes that this PR implements. -->
+
+# Preflight
+
+<!-- Please mark any checkboxes that do not apply to this pull request as [N/A]. -->
+
+**Code Style and Quality**
+
+- [ ] Unit tests have been implemented and passed.
+- [ ] Pyright static checking has been run and passed.
+- [ ] Pre-commit hooks have been run and passed.
+
+<!-- The unit tests can be invoked with `poetry run invoke tests` -->
+<!-- Pyright can be started with `pyright --skipunannotated` -->
+
+**Documentation**
+
+- [ ] New features are documented along with examples if relevant.
+- [ ] The documentation is [Sphinx](https://www.sphinx-doc.org/en/master/) and [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) compliant.
+
+<!--
+Thank you again!
+-->
diff --git a/.github/funding.yml b/.github/funding.yml
@@ -0,0 +1,12 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: colour-science # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
diff --git a/.github/workflows/continuous-integration-documentation.yml b/.github/workflows/continuous-integration-documentation.yml
@@ -0,0 +1,48 @@
+name: Continuous Integration - Documentation
+
+on: [push, pull_request]
+
+jobs:
+  continuous-integration-documentation:
+    name: ${{ matrix.os }} - Python ${{ matrix.python-version }}
+    strategy:
+      matrix:
+        os: [ubuntu-22.04]
+        python-version: [3.11]
+      fail-fast: false
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v1
+    - name: Environment Variables
+      run: |
+        echo "CI_PYTHON_VERSION=${{ matrix.python-version }}" >> $GITHUB_ENV
+        echo "CI_PACKAGE=colour_visuals" >> $GITHUB_ENV
+        echo "CI_SHA=${{ github.sha }}" >> $GITHUB_ENV
+        echo "MPLBACKEND=AGG" >> $GITHUB_ENV
+        echo "COLOUR_SCIENCE__DOCUMENTATION_BUILD=True" >> $GITHUB_ENV
+      shell: bash
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v1
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install Dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get --yes install latexmk texlive-full
+    - name: Install Poetry
+      env:
+        POETRY_VERSION: 1.4.0
+      run: |
+        curl -sSL https://install.python-poetry.org | POETRY_HOME=$HOME/.poetry python3 -
+        echo "$HOME/.poetry/bin" >> $GITHUB_PATH
+      shell: bash
+    - name: Install Package Dependencies
+      run: |
+        poetry run python -m pip install --upgrade pip
+        poetry install
+        poetry run python -c "import imageio;imageio.plugins.freeimage.download()"
+      shell: bash
+    - name: Build Documentation
+      run: |
+        poetry run invoke docs
+      shell: bash
diff --git a/.github/workflows/continuous-integration-quality-unit-tests.yml b/.github/workflows/continuous-integration-quality-unit-tests.yml
@@ -0,0 +1,62 @@
+name: Continuous Integration - Quality & Unit Tests
+
+on: [push, pull_request]
+
+jobs:
+  continuous-integration-quality-unit-tests:
+    name: ${{ matrix.os }} - Python ${{ matrix.python-version }}
+    strategy:
+      matrix:
+        os: [macOS-latest, ubuntu-22.04, windows-latest]
+        python-version: [3.9, '3.10', 3.11]
+      fail-fast: false
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v1
+      with:
+        submodules: true
+    - name: Environment Variables
+      run: |
+        echo "CI_PYTHON_VERSION=${{ matrix.python-version }}" >> $GITHUB_ENV
+        echo "CI_PACKAGE=colour_visuals" >> $GITHUB_ENV
+        echo "CI_SHA=${{ github.sha }}" >> $GITHUB_ENV
+        echo "COVERALLS_REPO_TOKEN=${{ secrets.COVERALLS_REPO_TOKEN }}" >> $GITHUB_ENV
+      shell: bash
+    - name: Set up Python 3.9 for Pre-Commit
+      uses: actions/setup-python@v1
+      with:
+        python-version: 3.9
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v1
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install Poetry
+      env:
+        POETRY_VERSION: 1.4.0
+      run: |
+        curl -sSL https://install.python-poetry.org | POETRY_HOME=$HOME/.poetry python3 -
+        echo "$HOME/.poetry/bin" >> $GITHUB_PATH
+      shell: bash
+    - name: Install Package Dependencies
+      run: |
+        poetry run python -m pip install --upgrade pip
+        poetry install
+        poetry run python -c "import imageio;imageio.plugins.freeimage.download()"
+      shell: bash
+    - name: Pre-Commit (All Files)
+      run: |
+        poetry run pre-commit run --all-files
+      shell: bash
+    - name: Test Optimised Python Execution
+      run: |
+        poetry run python -OO -c "import $CI_PACKAGE"
+      shell: bash
+    - name: Test with Pytest
+      run: |
+        poetry run python -W ignore -m pytest --doctest-modules --ignore=$CI_PACKAGE/examples --cov=$CI_PACKAGE $CI_PACKAGE
+      shell: bash
+    - name: Upload Coverage to coveralls.io
+      if: matrix.os == 'macOS-latest' && matrix.python-version == '3.11'
+      run: |
+        if [ -z "$COVERALLS_REPO_TOKEN" ]; then echo \"COVERALLS_REPO_TOKEN\" secret is undefined!; else poetry run coveralls; fi
+      shell: bash
diff --git a/.github/workflows/continuous-integration-static-type-checking.yml b/.github/workflows/continuous-integration-static-type-checking.yml
@@ -0,0 +1,29 @@
+name: Continuous Integration - Static Type Checking
+
+on: [push, pull_request]
+
+jobs:
+  continuous-integration-static-type-checking:
+    name: ${{ matrix.os }} - Python ${{ matrix.python-version }}
+    strategy:
+      matrix:
+        os: [macOS-latest]
+        python-version: [3.11]
+      fail-fast: false
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v1
+    - name: Environment Variables
+      run: |
+        echo "CI_PACKAGE=colour_visuals" >> $GITHUB_ENV
+      shell: bash
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v1
+      with:
+        python-version: ${{ matrix.python-version }}
+    - name: Install Package Dependencies
+      run: |
+        pip install -r requirements.txt
+    - name: Static Type Checking
+      run: |
+        pyright --skipunannotated
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,20 @@
+*.egg-info
+*.pyc
+*.pyo
+.DS_Store
+.coverage*
+.fleet
+.idea
+.ipynb_checkpoints
+.sandbox
+.vs
+.vscode
+
+__pycache__
+
+build
+colour_visuals.egg-info
+dist
+docs/_build
+docs/generated
+poetry.lock
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,6 @@
+[submodule "colour_visuals/resources/colour-visuals-tests-datasets"]
+	path = colour_visuals/resources/colour-visuals-tests-datasets
+	url = https://github.com/colour-science/colour-visuals-tests-datasets.git
+[submodule "colour_visuals/resources/colour-visuals-examples-datasets"]
+	path = colour_visuals/resources/colour-visuals-examples-datasets
+	url = https://github.com/colour-science/colour-visuals-examples-datasets.git
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,19 @@
+repos:
+-   repo: https://github.com/ikamensh/flynt/
+    rev: '1.0.1'
+    hooks:
+    -   id: flynt
+-   repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: 'v0.0.285'
+    hooks:
+    - id: ruff
+-   repo: https://github.com/psf/black
+    rev: 23.7.0
+    hooks:
+    - id: black
+      language_version: python3.9
+-   repo: https://github.com/keewis/blackdoc
+    rev: v0.3.8
+    hooks:
+    - id: blackdoc
+      language_version: python3.9
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.11"
+
+sphinx:
+   configuration: docs/conf.py
+
+formats:
+  - htmlzip
+  - pdf
+
+python:
+  install:
+    - requirements: docs/requirements.txt