copied demo files from project github task-5-deployment folder

.dockerignore

@@ -0,0 +1,17 @@
+
+#--- ignore select binary files/folders
+bin/images/sample*
+bin/models/*.pth
+bin/models/*.zip
+bin/testing
+
+
+#--- ignore all local data files; preserve/recreate folder structure
+data_host_mount
+data/tiles
+data/wsi
+
+
+#--- ignore all files within the _ignore folder
+_ignore
+

.gitattributes

@@ -33,3 +33,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*model_a* filter=lfs diff=lfs merge=lfs -text
+*.tiff filter=lfs diff=lfs merge=lfs -text
+data/demo_tiles/raw/*.tiff filter=lfs diff=lfs merge=lfs -text
+bin/models/deeplabv3*vhflip30/model_a* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,141 @@
+#--- specific to task5-deploy
+bin/images/sample*
+bin/models/*/*.pth
+bin/models/*.pth
+bin/models/*.zip
+bin/testing
+data/tiles
+data/wsi
+data_host_mount
+_ignore
+
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/

Dockerfile

@@ -0,0 +1,60 @@
+#--- PREREQS:  
+#   - create a local folder dedicated to WSI image mgmt:  (docker pwd)/data 
+#   - populate the folder with raw data, wsi and tiles
+#   - docker run --name <name> -v <local folder>
+
+#--- utilize a light linux distro for python apps
+FROM python:3.10.9-slim-bullseye
+
+#--- copy only the requirements.txt file
+#--- set docker image working directory to /app
+#--- Not:  this is reorg'd in an attempt to reduce the rebuilding of layers
+COPY ./requirements.txt /app/requirements.txt
+
+#--- set docker image working directory to /app
+WORKDIR /app
+
+#--- install all lib dependencies into the image
+RUN pip3 install -r ./requirements.txt
+RUN apt-get update && apt-get install ffmpeg libsm6 libxext6  -y
+
+#--- copy all files from the local pwd to the docker image /app folder
+#--- .dockerignore:  ensure no local data folders or files (images) are copied into the docker image/container 
+COPY . /app
+
+#--- for streamlit;  external 49400;  internal 39400
+#       localExec:  (from root folder) streamlit run app.py --server.port=39400 --server.maxUploadSize=2000
+EXPOSE 49400         
+#CMD ["streamlit", "run", "app.py", "--server.port=39400", "--server.maxUploadSize=2000"]
+
+
+#--- for fastapi;  external 49500;  internal 39500
+#       localExec:  (from root folder) uvicorn main:app --reload --workers 1 --host 0.0.0.0 --port 39500 
+EXPOSE 49500        
+#CMD ["uvicorn", "main:app", "--reload", "--host=0.0.0.0", "--port=39500"]
+
+#--- start streamlit and fastapi from a helper utility script
+#CMD ./util_startLocal_streamlitFastApi.sh
+CMD ./util_dockerPreRun.sh
+
+
+#--- to build/rebuild the image;  make sure you stop and remove the container if you are replacing/upgrading;  or change the version tag# from 0.1
+#    docker build -t img_stm_omdenasaudi_hcc:0.1 .
+
+#--- to tag the image prior to push to DockerHub;  docker login and then register user/image:tag
+#--- to push this image to DockerHub, example based on the repo:  kidcoconut73/img_stm_omdenasaudi_hcc
+#    docker tag img_omdenasaudi_hcc:0.1 kidcoconut73/img_stm_omdenasaudi_hcc:demo
+#    docker tag img_omdenasaudi_hcc:0.1 kidcoconut73/img_stm_omdenasaudi_hcc:0.1
+#    docker push kidcoconut73/img_stm_omdenasaudi_hcc:demo
+
+#--- to run the container from the image;  specific port mapping (-p) vs any available port mapping (-P)
+#    docker run -p 49400:39400 -p 49500:39500 --name ctr_stmOmdenaSaudiHcc -v ./data:/app/data img_stm_omdenasaudi_hcc:0.1
+#    docker run -p 49400:39400 -p 49500:39500 --name ctr_stmOmdenaSaudiHcc img_stm_omdenasaudi_hcc:0.1
+#    docker run -P --name ctr_stmOmdenaHcc img_stm_omdenasaudi_hcc:0.1                   #--- open all ports defined by Docker EXPOSE
+
+#--- ISSUE:  uvicorn bug does not allow ctl-C break of fastapi through terminal
+#--- WORKAROUND:  you have to run a docker or docker compose kill cmd;  eg docker kill <ctr_name>
+
+
+#---    Docker build log
+#       from python:3.10.9-slim-bullseye                    size:  4.21gb       time:  >yyys

README.md

@@ -6,6 +6,7 @@ colorTo: green
 sdk: docker
 pinned: false
 license: mit
+app_port: 49400
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

app.py

@@ -0,0 +1,26 @@
+'''
+    toExecute:  (from root app folder) ... streamlit run app.py
+'''
+import streamlit as st
+#from uix import lit_sidebar as lit_sideBar
+import uix.lit_sidebar as litSideBar
+
+
+#--- streamlit:  specify title and logo
+st.set_page_config(
+            page_title='Omdena Saudi Arabia - Liver HCC Diagnosis with XAI', 
+            #page_icon='https://cdn.freebiesupply.com/logos/thumbs/1x/nvidia-logo.png', 
+            layout="wide")
+st.header("Omdena Saudi Arabia - Liver HCC Diagnosis with XAI")
+st.markdown('---')
+
+
+#--- streamlit:  add a sidebar 
+litSideBar.init()
+
+
+#if __name__ == '__main__':
+#    st.run("main:app", host="0.0.0.0", port=49300, reload=True)
+#   streamlit run app.py --server.port 49400 --server.maxUploadSize 2000 
+
+#aryPkg[moduleNames.index(page)].run()

bin/models/util_joinModel.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+<<blkHeader
+Name:       util_joinModel
+Purpose:    reconstitutes a split pyTorch binary model with weights, into a single binary file
+Usage:      ./util_joinModel.sh <source pattern match> <dest model file>
+            - the first arg has to be wrapped in single quotes to ensure that bash does not expand wildcards
+Prereqs:    a model folder within bin/models;  containing a split pyTorch model.pth as 1 or more model_nn files 
+Todo:       get the parent folder name and use this as the name for the model file
+blkHeader
+
+#--- dependencies
+#none
+
+
+#---    initialization
+#---    $1:  first arg;  source pattern match;  eg './bin/models/deeplabv3*vhflip30/model_a*';  Note that this is wildcarded so must be in quotes
+#---    $n:  last arg; dest model file;  eg. ./bin/models/model.pth
+strPth_patternMatch=$1
+strPth_filMatch=( $strPth_patternMatch )        #--- expand the pattern match; get the first value of the pattern match
+strPth_parentFld=$(dirname $strPth_filMatch)    #--- get the parent dir of the first file match
+strPth_mdlFile=${@: -1}                         #--- Note:  this gets the last arg;  otherwise the 2nd arg would be an iteration of the 1st arg wildcard
+
+#echo "TRACE:  strPth_patternMatch= $strPth_patternMatch"
+#echo "TRACE:  strPth_filMatch= $strPth_filMatch"
+#echo "TRACE:  strPth_parentFld= $strPth_parentFld"
+#echo "TRACE:  strPth_mdlFile= $strPth_mdlFile"
+
+#--- reconstitute model
+#--- Note:  cat command does not work with single-quote literals; do not reapply single quotes
+#echo "cat ${strPth_patternMatch} > ${strPth_mdlFile}"
+cat ${strPth_patternMatch} > ${strPth_mdlFile}

bin/models/util_splitModel.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+<<blkHeader
+Name:       util_splitModel
+Purpose:    convenience script to split a single pyTorch .pth model file with weights into smaller 10MB chunks in order to store within github
+Usage:      ./util_splitModel.sh <src model file> <dest folder>
+            - the first arg has to be wrapped in single quotes to ensure that bash does not expand wildcards
+Prereqs:    a pytorch model file 
+Todo:       get the parent folder name and use this as the name for the model file
+blkHeader
+
+#--- dependencies
+#none
+
+
+#---    initialization
+#---    $1:  first arg; the source model file; eg ./bin/models/model.pth
+#---    $n:  last arg; dest model path;  eg. ./test_model_folder
+strPth_mdlFile=$1
+strPth_mdlFolder=$2
+strPrefix='/model_'
+
+#echo "TRACE:  strPth_mdlFile= $strPth_mdlFile"
+echo "TRACE:  strPth_mdlFolder= $strPth_mdlFolder"
+
+#--- ensure the target dir exists
+mkdir -p $strPth_mdlFolder
+
+#--- split the model into smaller chunks
+echo "split -b 10M $strPth_mdlFile $strPth_mdlFolder$strPrefix"
+split -b 10M $strPth_mdlFile $strPth_mdlFolder$strPrefix

config.toml

@@ -0,0 +1,3 @@
+[server]
+
+maxUploadSize = 2000		#--- increased from default 200MB to 2000MB

main.py

@@ -0,0 +1,92 @@
+'''
+    purpose:     fastAPI routing 
+'''
+
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+from fastapi import APIRouter, Request, Response
+from fastapi.templating import Jinja2Templates
+import uvicorn
+
+#--- import custom libraries
+import lib.utils as libUtils
+
+
+#--- imported route handlers
+from routes.api.rte_api import rteApi
+from routes.api.rte_wsi import rteWsi
+from routes.api.rte_tiles import rteTiles
+
+
+#--- fastAPI self doc descriptors
+description = """
+    Omdena Saudi Arabia:  Liver Cancer HCC Diagnosis with XAI
+    
+    <insert purpose>
+
+    ## key business benefit #1
+    ## key business benefit #2
+    ## key business benefit #3
+
+    You will be able to:
+    * key feature #1
+    * key feature #2
+    * key feature #3
+"""
+
+app = FastAPI(
+    title="App:  Omdena Saudi Arabia - Liver Cancer HCC Diagnosis with XAI",
+    description=description,
+    version="0.0.1",
+    terms_of_service="http://example.com/terms/",
+    contact={
+        "name": "Iain McKone",
+        "email": "iain.mckone@gmail.com",
+    },
+    license_info={
+        "name": "Apache 2.0",
+        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
+    },
+)
+
+
+#--- configure route handlers
+app.include_router(rteWsi, prefix="/api/wsi")
+app.include_router(rteTiles, prefix="/api/tiles")
+app.include_router(rteApi, prefix="/api")
+
+#app.include_router(rteQa, prefix="/qa")
+
+
+m_kstrPath_templ = libUtils.pth_templ
+m_templRef = Jinja2Templates(directory=str(m_kstrPath_templ))
+
+
+def get_jinja2Templ(request: Request, pdfResults, strParamTitle, lngNumRecords, blnIsTrain=False, blnIsSample=False):
+    lngNumRecords = min(lngNumRecords, libUtils.m_klngMaxRecords)
+    if (blnIsTrain):  strParamTitle = strParamTitle + " - Training Data"
+    if (not blnIsTrain):  strParamTitle = strParamTitle + " - Test Data"
+    if (blnIsSample):  lngNumRecords = libUtils.m_klngSampleSize
+    strParamTitle = strParamTitle + " - max " + str(lngNumRecords) + " rows"
+
+    kstrTempl = 'templ_showDataframe.html'
+    jsonContext = {'request': request, 
+                'paramTitle': strParamTitle,
+                'paramDataframe': pdfResults.sample(lngNumRecords).to_html(classes='table table-striped')
+            }
+    result = m_templRef.TemplateResponse(kstrTempl, jsonContext)
+    return result
+
+
+#--- get main ui/ux entry point
+@app.get('/')
+def index():
+    return {
+        "message": "Landing page:  Omdena Saudi Arabia - Liver HCC Diagnosis with XAI"
+    }
+
+
+
+if __name__ == '__main__':
+    uvicorn.run("main:app", host="0.0.0.0", port=49300, reload=True)
+#CMD ["uvicorn", "main:app", "--host=0.0.0.0", "--reload"]

requirements.txt

@@ -0,0 +1,68 @@
+#--- 20230530:  commented out all secondary packages as they were causing the huggingfaceSpace to fail 
+
+#altair==4.2.2
+#anyio==3.6.2
+#attrs==23.1.0
+#backports.zoneinfo==0.2.1
+#blinker==1.6.2
+#cachetools==5.3.0
+#certifi==2023.5.7
+#charset-normalizer==3.1.0
+#click==8.1.3
+#decorator==5.1.1
+#entrypoints==0.4
+fastapi==0.95.2
+#gitdb==4.0.10
+#git-lfs
+#GitPython==3.1.31
+grad-cam
+#h11==0.14.0
+#idna==3.4
+#importlib-metadata==6.6.0
+#importlib-resources==5.12.0
+#ipython-genutils==0.2.0
+Jinja2==3.1.2
+joblib==1.2.0
+jsonschema==4.17.3
+#markdown-it-py==2.2.0
+#MarkupSafe==2.1.2
+#mdurl==0.1.2
+numpy==1.24.3
+#packaging==23.1
+pandas==1.5.3
+#Pillow==9.5.0
+#pkgutil_resolve_name==1.3.10
+plotly==5.14.1
+#protobuf==3.20.3
+#pyarrow==12.0.0
+#pydantic==1.10.8
+#pydeck==0.8.1b0
+#Pygments==2.15.1
+#Pympler==1.0.1
+#pyrsistent==0.19.3
+#python-dateutil==2.8.2
+#pytz==2023.3
+#PyYAML==6.0
+#requests==2.31.0
+#rich==13.3.5
+scikit-learn==1.1.1
+#scipy==1.10.1
+#six==1.16.0
+#smmap==5.0.0
+#sniffio==1.3.0
+#starlette==0.27.0
+streamlit==1.24.0
+#tenacity==8.2.2
+#threadpoolctl==3.1.0
+#toml==0.10.2
+#toolz==0.12.0
+torch
+torchvision
+#tornado==6.3.2
+#typing_extensions==4.6.2
+#tzlocal==5.0.1
+#urllib3==2.0.2
+uvicorn==0.22.0
+#validators==0.20.0
+#watchdog==3.0.0
+#zipp==3.15.0

routes/api/rte_api.py

@@ -0,0 +1,79 @@
+from fastapi import APIRouter, Request, Response
+from fastapi.responses import JSONResponse
+
+import pandas as pd
+import json
+
+#import lib.claims as libClaims
+#from lib.models import mdl_utils, mdl_xgb
+
+
+rteApi = APIRouter()
+
+
+#--- 
+@rteApi.get('/')
+def api_entry():
+    return {
+        "message": "api routing - welcome to Omdena Saudi HCC api"
+    }
+
+
+
+'''
+#--- >>> SAMPLE CODE BELOW
+#--- return json for claims data (merged)
+#--- note:  current is kaggle, but future could include from yyyymm filter
+@rteApi.get('/claims', response_class = JSONResponse)
+def api_getClaims(request: Request, response: Response):
+    pdfClaims = libClaims.load_claims()
+    jsonSample = pdfClaims.head(50).to_json(orient="records", indent=4)
+    result = json.loads(jsonSample)
+    return result
+
+
+#--- return json for featEng
+@rteApi.get('/claims/doFeatEng/', response_class = JSONResponse)
+def tst_claims_featEng():
+    pdfClaims = libClaims.load_claims()
+    pdfFeatEng = libClaims.do_featEng(pdfClaims)
+    jsonSample = pdfClaims.head(50).to_json(orient="records", indent=4)
+    result = json.loads(jsonSample)
+    return result
+
+
+@rteApi.get('/claims/doStdScaling/', response_class = JSONResponse)
+def tst_claims_stdScaling():
+    pdfClaims = libClaims.load_claims()
+    pdfFeatEng = libClaims.do_featEng(pdfClaims)
+    pdfScaled = mdl_utils.doClaims_stdScaler_toPdf(pdfFeatEng)
+
+    jsonSample = pdfClaims.head(50).to_json(orient="records", indent=4)
+    result = json.loads(jsonSample)
+    return result
+
+
+@rteApi.get('/claims/predict/superv', response_class = JSONResponse)
+@rteApi.get('/claims/predict/xgb', response_class = JSONResponse)
+def predict_xgb():
+    #--- load test data
+    pdfClaims = libClaims.load_claims()
+    pdfFeatEng = libClaims.do_featEng(pdfClaims)
+
+    npaScaled = mdl_utils.do_stdScaler(pdfFeatEng)
+    pdfScaled = mdl_utils.do_stdScaler_toPdf(npaScaled)
+  
+    ndaPredict = mdl_xgb.predict(npaScaled)
+    pdfPredict = pd.DataFrame(ndaPredict)
+
+    #--- stitch the grouped data with the labels
+    pdfResults = pdfScaled.copy()
+    pdfResults.insert(0, "hasAnom?", pdfPredict[0])
+
+    #--- filter to only those rows that are flagged with an anomaly
+    pdfResults = pdfResults[pdfResults['hasAnom?'] > 0] 
+
+    jsonSample = pdfResults.head(50).to_json(orient="records", indent=4)
+    result = json.loads(jsonSample)
+    return result
+'''

routes/api/rte_tiles.py

@@ -0,0 +1,198 @@
+from fastapi import APIRouter, Request, Response
+from fastapi.responses import HTMLResponse
+import numpy as np
+import cv2
+import os
+
+
+import main as libMain
+from lib import utils as libUtils
+
+
+m_kstrFile = __file__
+m_blnTraceOn = True
+
+m_kstrPath_templ = libUtils.pth_templ
+
+
+rteTiles = APIRouter()
+
+
+#--- 
+@rteTiles.get('/')
+def api_tiles():
+    return {
+        "message": "tiles api endpoint - welcome to the endpoint for tile image processing"
+    }
+
+
+#--- 
+@rteTiles.get('/raw/upload')
+def api_tilesRawUpload():
+    '''
+        process an array of uploaded raw Tiles (from external app path)
+        - cleanup all old raw images in /data/tiles/raw
+        - save uploads to /data/tiles/raw
+        - create tile class obj;  capture file path, size, zoomMagnif, etc
+        - create array of tile class objs
+        - return(s) json
+            - ack tile/raw uploads with info/attribs
+    '''
+    return {
+        "message": "tilesRawUpload endpoint - file processing of raw tile images"
+    }
+
+
+@rteTiles.get('/raw/norm')
+def api_tilesRawNormalize(strPthTile):
+    '''
+        process an array of uploaded raw Tiles (from internal app path)
+        - cleanup all old norm images in /data/tiles/norm
+        - process tile normalization ops
+        - save norm tiles to /data/tiles/norm
+        - create tile class obj;  capture file path, size, zoomMagnif, etc
+        - return(s) json
+            - ack tile/norms with info/attribs
+    '''
+    #--- get file attributes
+    strFilPath, strFilName = os.path.split(strPthTile)
+    strPthRaw = strPthTile
+
+    #--- load the tile as a binary object
+    with open(strPthRaw,"rb") as filRaw: 
+        imgRaw = filRaw.read()
+
+    #--- Resize Tiles to 256x256
+    #--- Note:  imgTile is a buffer object.  
+    aryNp = np.frombuffer(imgRaw, np.uint8)
+    imgTemp = cv2.imdecode(aryNp, cv2.IMREAD_COLOR)
+    imgResized = cv2.resize(imgTemp, (256, 256))
+
+    #--- save the normalized file 
+    imgNorm = imgResized
+    strPthNorm = "data/tiles/norm", strFilName
+    with open(os.path.join(strPthNorm),"wb") as filNorm: 
+        filNorm.write(imgResized.buffer)
+    return strPthNorm
+    """ return {
+        "message": "tileRawNorm endpoint - normalization of raw tile images"
+    }
+ """
+
+@rteTiles.get('/norm/upload')
+def api_tilesNormUpload():
+    '''
+        process an array of uploaded norm Tiles (from external app path)
+        - cleanup all old norm images in /data/tiles/norm
+        - save uploads to /data/tiles/norm
+        - create tile class obj;  capture file path, size, zoomMagnif, etc
+        - create array of tile class objs
+        - return(s) json
+            - ack tile/norm uploads with info/attribs
+    '''
+    return {
+        "message": "tilesNormUpload endpoint - file processing of norm tile images"
+    }
+
+
+@rteTiles.get('/norm/preprocess')
+def api_tilesNormPreprocess():
+    '''
+        preprocess an array of uploaded norm Tiles (from internal app path)
+        - perform remaining pre-processing of tiles prior to model prediction
+        - cleanup all old preproc images in /data/tiles/preproc
+        - save preproc tiles to /data/tiles/preproc
+        - create tile class obj;  capture file path, size, zoomMagnif, etc
+        - return(s) json
+            - ack tile/preproc with info/attribs
+    '''
+    return {
+        "message": "tileNormPreprocess endpoint - preprocessing of normalized tile images"
+    }
+
+
+@rteTiles.get('/preproc/upload')
+def api_tilesPreprocUpload():
+    '''
+        process an array of uploaded preprocessed Tiles (from external app path)
+        - cleanup all old preproc images in /data/tiles/preproc
+        - save uploads to /data/tiles/preproc
+        - create tile class obj;  capture file path, size, zoomMagnif, etc
+        - create array of tile class objs
+        - return(s) json
+            - ack tile/preproc uploads with info/attribs
+    '''
+    return {
+        "message": "tilesPreprocUpload endpoint - manage upload of preprocessed tile images, in prep for modelling/prdictions"
+    }
+
+
+@rteTiles.get('/preproc/augment')
+def api_tilesPreprocAugment():
+    '''
+        process an array of uploaded preprocessed tiles (from internal app path)
+        - cleanup all old augmented tiles in /data/tiles/augm
+        - perform augments of tiles prior to model prediction (translation, rotation, transforms)
+        - save augmented tiles to /data/tiles/augm
+        - create tile class obj;  capture file path, size, zoomMagnif, etc
+        - return(s) json
+            - ack tile/augm with info/attribs
+    '''
+    return {
+        "message": "tilePreprocAugment endpoint - augment tile images"
+    }
+
+
+@rteTiles.get('/augm/upload')
+def api_tilesAugmUpload():
+    '''
+        process an array of augmented tiles (from external app path)
+        - cleanup all old augm images in /data/tiles/augm
+        - save uploads to /data/tiles/augm
+        - create tile class obj;  capture file path, size, zoomMagnif, etc
+        - create array of tile class objs
+        - return(s) json
+            - ack tile/augm uploads with info/attribs
+    '''
+    return {
+        "message": "tilesAugmUpload endpoint - manage upload of augmented tile images, in prep for modelling/predictions"
+    }
+
+
+#--- 
+@rteTiles.get('/raw/predict')
+def api_tileRawPredict():
+    return {
+        "message": "tile_rawPredict api endpoint - welcome to the endpoint for tile predictions"
+    }
+
+
+#--- 
+@rteTiles.get('/norm/segment')
+def api_tileNormPredict():
+    return {
+        "message": "tile_normPredict api endpoint - welcome to the endpoint for tile predictions"
+    }
+
+#--- 
+@rteTiles.get('/norm/predict')
+def api_tileNormPredict():
+    return {
+        "message": "tile_normPredict api endpoint - welcome to the endpoint for tile predictions"
+    }
+
+
+#--- 
+@rteTiles.get('/preproc/predict')
+def api_tilePreprocPredict():
+    return {
+        "message": "tile_preprocPredict api endpoint - welcome to the endpoint for tile predictions"
+    }
+
+
+#--- 
+@rteTiles.get('/augm/predict')
+def api_tileAugmPredict():
+    return {
+        "message": "tile_augmPredict api endpoint - welcome to the endpoint for tile predictions"
+    }

routes/api/rte_wsi.py

@@ -0,0 +1,56 @@
+from fastapi import APIRouter, Request, Response
+from fastapi.responses import HTMLResponse
+
+
+import main as libMain
+from lib import utils as libUtils
+
+
+m_kstrFile = __file__
+m_blnTraceOn = True
+
+m_kstrPath_templ = libUtils.pth_templ
+
+
+rteWsi = APIRouter()
+
+
+#--- 
+@rteWsi.get('/')
+def api_wsi():
+    return {
+        "message": "wsi api endpoint - welcome to the endpoint for wsi image processing"
+    }
+
+
+#--- 
+@rteWsi.get('/upload')
+def api_wsiUpload():
+    '''
+        process a single uploaded WSI image (from external app path)
+        - cleanup all old WSI images in /data/wsi/raw
+        - save upload to /data/wsi/raw
+        - create wsi class obj;  capture file path, size, zoomMagnif, etc
+        - return(s) json
+            - ack wsi upload with info/attribs
+    '''
+    return {
+        "message": "wsiUpload endpoint - file processing of one uploaded wsi image"
+    }
+
+
+#--- 
+@rteWsi.get('/chunk')
+def api_wsiChunk():
+    '''
+        process a single WSI image  (from internal app path)
+        - create wsi class obj;  capture file path, size, zoomMagnif, etc
+        - kick off tile chunking process;  
+        - save tiles to /data/tiles/raw
+        - return(s) json
+            - ack wsi upload with info/attribs
+            - ack of tiles created:  total count;  names, paths, attribs (dimensions)
+    '''
+    return {
+        "message": "wsiLoad endpoint - for chunking of wsi image to one or more tiles"
+    }

routes/qa/rte_qa.py

@@ -0,0 +1,17 @@
+from fastapi import APIRouter
+
+
+m_kstrFile = __file__
+m_blnTraceOn = True
+
+
+rteQa = APIRouter()
+
+
+@rteQa.get('/')
+@rteQa.get('/verif')
+@rteQa.get('/valid')
+def qa_entry():
+    return {
+        "message": "qa routing - welcome to Omdena Saudi HCC qa"
+    }

templ/templ_results.html

@@ -0,0 +1,4 @@
+<!DOCTYPE html>
+<html>
+    <body>{{ dataframe | safe }}</body>
+</html>

templ/templ_showDataframe.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <title>Fourthbrain Capstone:  Healthcare Anomalies</title>
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.1/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-+0n0xVW2eSR5OomGNYDnhzAbDsOXxcvSN1TPprVMTNDbiYZCxYbOOl7+AMvyTG2x" crossorigin="anonymous">
+</head>
+<body>
+
+    <h2>{{ paramTitle }}:</h2>
+
+    <!-- Mark data as safe, otherwise it will be rendered as a string -->
+    {{ paramDataframe | safe }}
+</body>
+</html>

uix/lit_packages.py

@@ -0,0 +1,31 @@
+import importlib
+
+
+#--- return a list of streamlit packages/pages to render
+def packages():
+        #--- 
+        ary_pkg = []
+        ary_pkg.extend(['lit_continentData',
+                        'lit_countryData'
+                        ])
+        return ary_pkg
+
+
+
+def get_aryPkgDescr():
+        #--- load list of pages to display
+        aryDescr = []
+        aryPkgs = []
+
+        aryModules = packages()
+        for modname in aryModules:
+                m = importlib.import_module('.'+ modname,'uix')
+                aryPkgs.append(m)
+
+                #--- use the module description attribute if it exists 
+                #--- otherwise use the module name
+                try:
+                        aryDescr.append(m.description)
+                except:
+                        aryDescr.append(modname)
+        return [aryDescr, aryPkgs]

uix/lit_sidebar.py

@@ -0,0 +1,96 @@
+import streamlit as st
+import importlib
+from uix import lit_packages
+
+from uix.pages import lit_home, lit_about, lit_diagnosis
+from uix.pages import lit_qaConfigCheck
+
+
+#--- alt define sidebar pages
+m_aryPages = {
+    "Home":                         lit_home,           #--- TODO:  update
+    "Diagnosis:  One Tile":         lit_diagnosis,
+    #"QA:  File Check":              lit_qaConfigCheck,         
+    "About":                        lit_about
+}
+
+
+#--- define module-level vars
+m_aryModNames = lit_packages.packages()
+m_aryDescr = [] 
+m_aryMods = []
+
+
+def init():
+    #--- upper panel
+    with st.sidebar:
+        kstrUrl_image = "bin/images/logo_omdena_saudi.png"
+        st.sidebar.image(kstrUrl_image, width=200)
+        #st.sidebar.markdown('Omdena Saudi - Liver HCC Diagnosis with XAI') 
+ 
+
+    #--- init checkboxes
+    strKey = st.sidebar.radio("", list(m_aryPages.keys()))
+    pagSel = m_aryPages[strKey]
+    writePage(pagSel)
+
+
+
+def init_selectBox():
+    #--- init module array of page names, and descr
+    init_modDescrAry()
+
+    # Display the sidebar with a menu of apps
+    kstrMsg = """
+            __Claims Anomaly Views__
+            """
+    with st.sidebar:
+        st.markdown('---')
+        st.markdown(kstrMsg)
+        page = st.selectbox('Select:', m_aryModNames, format_func=fmt_modName) 
+
+    #--- display sidebar footer
+    with st.sidebar:
+        st.markdown('---')
+        st.write('Developed by Chavarria, McKone, Sharma')
+        st.write('Contact at iain.mckone@gmail.com')
+    
+    # Run the chosen app
+    m_aryMods[m_aryModNames.index(page)].run()
+
+
+
+def init_modDescrAry():
+    #--- init global array of page names, and descr
+    #--- note:  you need to specify global scope for fxns to access module-level variables 
+    global m_aryMods
+    global m_aryDescr
+
+    m_aryMods = []
+    m_aryDescr = []
+    for modName in m_aryModNames:
+        modTemp = importlib.import_module('.'+modName,'uix')
+        m_aryMods.append(modTemp)
+
+        #--- If the module has a description attribute use that in the 
+        #--- select box otherwise use the module name
+        try:
+            m_aryDescr.append(modTemp.description)
+        except:
+            m_aryDescr.append(modName)
+
+
+
+#--- display the app descriptions instead of the module names in the selctbox
+def fmt_modName(strName):
+    global m_aryModNames
+    global m_aryDescr
+    return m_aryDescr[m_aryModNames.index(strName)]
+
+
+
+def writePage(uixFile):  
+    #--- writes out the page for the selected combo
+  
+    # _reload_module(page)
+    uixFile.run()

uix/pages/lit_about.py

@@ -0,0 +1,22 @@
+#--- about page
+import streamlit as st
+
+description = "About"
+def run():
+
+    print("\nINFO (lit_about.run)  loading ", description, " page ...") 
+
+    #--- 
+    #st.experimental_memo.clear()            #--- try to clear cache each time this page is hit
+    #st.cache_data.clear()
+
+    st.markdown('### About')
+    st.markdown('### Omdena Saudi:  Liver HCC Diagnosis with XAI')
+    st.markdown('#### Chapter Lead:  Dr. Shai')
+
+    st.markdown(
+        """
+            About page
+        """,
+            unsafe_allow_html=True,
+        )

uix/pages/lit_diagnosis.py

@@ -0,0 +1,470 @@
+#--- anomaly detection - supervised page
+import streamlit as st
+import pandas as pd
+import plotly.express as px
+import plotly.graph_objects as go
+import numpy as np
+
+import matplotlib.pyplot as plt
+from PIL import Image
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from torchvision.models.segmentation import deeplabv3_resnet50
+from torchvision.transforms.functional import to_tensor
+from pytorch_grad_cam import GradCAM
+from pytorch_grad_cam.utils.image import show_cam_on_image
+
+import lib.utils as libUtils
+
+import sys
+import os
+
+description = "Diagnosis"
+m_kblnTraceOn = True                                  #--- enable/disable module level tracing
+
+
+#--- model initializations
+#data_batch_size = 3         #--- decrease the number of images loaded, processed if the notebook crashes due to limited RAM
+#NUM_EPOCHS = 10 # 50
+#BATCH_SIZE = data_batch_size
+NUM_CLASSES = 3
+
+# path to save model weights
+#BESTMODEL_PATH = r"model_deeplabv3_r50_full_training_dataset_80-20_split_10epochs_no-norm_vhflip30.pth"  #--- path to save model weights
+BESTMODEL_PATH = r"model.pth"
+MODEL_FULLPATH = 'bin/models/' + BESTMODEL_PATH
+model_path = MODEL_FULLPATH
+
+DEFAULT_DEVICE_TYPE = ('cuda' if torch.cuda.is_available() else 'cpu')       #--- cuda if gpu; cpu if on Colab Free
+DEFAULT_BACKBONE_MODEL = 'r50'
+backbone_model_name = DEFAULT_BACKBONE_MODEL
+
+
+
+def run():
+    #--- note:  in python, you need to specify global scope for fxns to access module-level variables 
+    global m_kbln_TraceOn
+    print("\nINFO (litDiagnosis.run)  loading ", description, " page ...") 
+
+
+    #--- page settings
+    if (m_kblnTraceOn):  print("TRACE1 (litDiagnosis.run):  Initialize Page Settings ...")
+    st.header("Single Tile Diagnosis")
+
+
+    #--- provide file drag/drop capability
+    m_blnDisableDragDrop = False
+    if(not m_blnDisableDragDrop): 
+        #btnSave = st.button("Save")
+        imgDropped = st.file_uploader("Upload a single Tile", type=["png", "jpg", "tif", "tiff", "img"])
+        m_blnDisableDragDrop = (imgDropped is None)
+
+
+    #if (True):
+        try:
+
+            #--- show:  
+            #if (m_kblnTraceOn):  print("TRACE (litDiagnosis.run):  load WSI ...")
+            if (m_blnDisableDragDrop):
+                #--- load wsi 
+                print("")
+            else:
+                #--- display uploaded file details
+                if (m_kblnTraceOn):  print("TRACE1 (litDiagnosis.run):  Print upload file details ...")
+                st.write(
+                    "FileName:", "   ", imgDropped.name, "\n",
+                    "FileType:", "   ", imgDropped.type, "\n"
+                )
+
+                #--- display diagnosis results ... format (vertical)
+                #showDiagnosis_vert(imgDropped)
+                showDiagnosis_horiz(imgDropped)
+
+        except TypeError as e:
+            print("ERROR (litDiagnosis.run_typeError1):  ", e)
+
+        except:
+            e = sys.exc_info()
+            print("ERROR (litDiagnosis.run_genError1):  ", e)  
+
+
+        try:
+
+            #--- display WSI
+            #showImg_wsi(img)
+            #st.image("bin/images/sample_wsi.png", use_column_width=True)
+
+            print("")
+
+        except TypeError as e:
+            print("ERROR (litDiagnosis.run_typeError2):  ", e)
+
+        except:
+            e = sys.exc_info()
+            print("ERROR (litDiagnosis.run_genError2):  ", e)  
+
+
+def showImg_wsi(img):
+     print("")
+
+
+def readyModel_getPreds(imgDropped):
+    print("TRACE:  save raw tile ...")
+    strPth_tilRaw = save_tilRaw(imgDropped)
+    
+    #--- ready the model
+    print("TRACE:  ready base model ...")
+    mdlBase = readyBaseModel()
+    print("TRACE:  ready model with weights ...")
+    mdlWeights = readyModelWithWeights(mdlBase)
+    print("TRACE:  ready model with xai ...")
+    mdlXai = readyModelWithXAI(mdlWeights)
+
+    #--- get the XAI weighted prediction
+    print("TRACE:  get xai weighted pred ...")
+    output_pred, tns_batch = predXai_tile(mdlXai, strPth_tilRaw)
+
+    #--- get the GRADCAM predictions
+    print("TRACE:  get GRADCAM preds ...")
+    cam_img_bg, cam_img_wt, cam_img_vt = predGradCam_tile(output_pred, mdlXai, tns_batch)
+
+    print("TRACE:  return readyModel_getPreds ...")
+    return strPth_tilRaw, output_pred, cam_img_bg, cam_img_wt, cam_img_vt
+
+
+def showDiagnosis_horiz(imgDropped):
+
+    #--- copy the uploaded file to data/tiles/raw       
+    st.write("#")
+
+    #--- ready the model, get predictions
+    print("TRACE2:  ready model ...")
+    strPth_tilRaw, xai_pred, cam_img_bg, cam_img_wt, cam_img_vt = readyModel_getPreds(imgDropped)
+
+    #--- display the raw prediction:  headers
+    print("TRACE2:  display raw preds, headers ...")
+    colRaw, colPred, colGradBack, colGradWhole, colGradViable = st.columns(5)
+    colRaw.write("Raw Tile")
+    colPred.write("Prediction")
+    colGradBack.write("GradCAM:  Background")
+    colGradWhole.write("GradCAM:  Whole Tumor")
+    colGradViable.write("GradCAM:  Viable Tumor")
+
+    #--- display the raw prediction:  images
+    colRaw, colPred, colGradBack, colGradWhole, colGradViable = st.columns(5)
+    showCol_rawTil(colRaw, strPth_tilRaw)
+    showCol_predTil(colPred, xai_pred[0], strPth_tilRaw)
+    showCol_gradCamImg("imgGradCam_bg", colGradBack, cam_img_bg[0])
+    showCol_gradCamImg("imgGradCam_wt", colGradWhole, cam_img_wt[0])
+    showCol_gradCamImg("imgGradCam_vt", colGradViable, cam_img_vt[0])
+
+
+def showCol_rawTil(colRaw, strPth_tilRaw):
+    print("TRACE3:  showCol_rawTil ...")
+    colRaw.image(strPth_tilRaw, width=400, use_column_width=True)
+
+
+def showCol_predTil(colPred, xai_pred, strPth_tilRaw):
+    kstrPth_tilePred = "data/tiles/pred/"
+    strFilName = os.path.basename(strPth_tilRaw)
+    strFil_tilePred = kstrPth_tilePred + strFilName
+
+    print("TRACE3:  showCol_predTil2 ... ", strFil_tilePred)
+    argmax_mask = torch.argmax(xai_pred, dim=0)
+    preds = argmax_mask.cpu().squeeze().numpy()
+
+    cmap = plt.cm.get_cmap('tab10', 3)  # Choose a colormap with 3 colors
+    print("TRACE3:  typeOf(preds) ...", type(preds))
+
+    print("TRACE3:  save pred image ...")
+    plt.imsave(strFil_tilePred, preds, cmap=cmap, vmin=0, vmax=2)
+
+    print("TRACE3:  load image ...", strFil_tilePred)
+    colPred.image(strFil_tilePred, width=400, use_column_width=True)
+
+
+def showCol_gradCamImg(strImgContext, colGradCam, cam_img):
+    print("TRACE3:  showCol_gradImg ... ", strImgContext)
+    imgGradCam = Image.fromarray(cam_img)
+    colGradCam.image(imgGradCam, width=400, use_column_width=True)
+
+
+def showDiagnosis_vert(imgDropped):
+
+    #--- copy the uploaded file to data/tiles/raw       
+    st.write("#")
+
+    #--- ready the model, get predictions
+    strPth_tilRaw, xai_pred, cam_img_bg, cam_img_wt, cam_img_vt = readyModel_getPreds(imgDropped)
+
+    #--- display all predictions
+    '''
+    strPth_tilPred = save_tilPred(output_pred)
+    strPth_tilGradBg = save_tilGradBg(cam_img_bg)
+    strPth_tilGradWt = None
+    strPth_tilGradVt = None
+    '''
+
+    #--- display the raw image
+    lstDescr = ["Raw Tile", "Prediction", "GradCam: Background", "GradCam: Whole Tumor", "GradCam: Viable Tumor"]
+    lstImages = [strPth_tilRaw, strPth_tilRaw, strPth_tilRaw, strPth_tilRaw, strPth_tilRaw]
+
+    #--- display the raw prediction 
+    for imgIdx in range(len(lstImages)):
+        colDescr, colImage = st.columns([0.25, 0.75])
+        colDescr.write(lstDescr[imgIdx])
+        colImage.image(lstImages[imgIdx], width=400, use_column_width=True)
+
+
+def save_tilRaw(imgDropped):
+    #--- copy the uploaded raw Tile to data/tiles/raw
+    kstrPth_tileRaw = "data/tiles/raw/"
+    strFil_tileRaw = kstrPth_tileRaw + imgDropped.name
+    with open(strFil_tileRaw,"wb") as filUpload: 
+        filUpload.write(imgDropped.getbuffer()) 
+    print("TRACE:  uploaded file saved to ", strFil_tileRaw)        
+    return strFil_tileRaw
+
+
+def prepare_model(backbone_model="mbv3", num_classes=2):
+
+    # Initialize model with pre-trained weights.
+    weights = 'DEFAULT'
+    if backbone_model == "mbv3":
+        model = None
+        #model = deeplabv3_mobilenet_v3_large(weights=weights)
+
+    elif backbone_model == "r50":
+        model = deeplabv3_resnet50(weights=weights)
+
+    elif backbone_model == "r101":
+        model = None
+        #model = deeplabv3_resnet101(weights=weights)
+        
+    else:
+        raise ValueError("Wrong backbone model passed. Must be one of 'mbv3', 'r50' and 'r101' ")
+
+    # Update the number of output channels for the output layer.
+    # This will remove the pre-trained weights for the last layer.
+    model.classifier[-1] = nn.Conv2d(model.classifier[-1].in_channels, num_classes, kernel_size=1)
+    model.aux_classifier[-1] = nn.Conv2d(model.aux_classifier[-1].in_channels, num_classes, kernel_size=1)
+    return model
+
+
+# computes IoU or Dice index
+def intermediate_metric_calculation(predictions, targets,  use_dice=False,
+                                    smooth=1e-6, dims=(2, 3)):
+    # dims corresponding to image height and width: [B, C, H, W].
+
+    # Intersection: |G ∩ P|. Shape: (batch_size, num_classes)
+    intersection = (predictions * targets).sum(dim=dims) + smooth
+
+    # Summation: |G| + |P|. Shape: (batch_size, num_classes).
+    summation = (predictions.sum(dim=dims) + targets.sum(dim=dims)) + smooth
+
+    if use_dice:
+        # Dice Shape: (batch_size, num_classes)
+        metric = (2.0 * intersection) / summation
+    else:
+        # Union. Shape: (batch_size, num_classes)
+        union = summation - intersection + smooth
+
+        # IoU Shape: (batch_size, num_classes)
+        metric = intersection /  union
+
+    # Compute the mean over the remaining axes (batch and classes).
+    # Shape: Scalar
+    total = metric.mean()
+
+    #print(f"iou = {total}")
+    return total
+
+
+def convert_2_onehot(matrix, num_classes=3):
+    '''
+    Perform one-hot encoding across the channel dimension.
+    '''
+    matrix = matrix.permute(0, 2, 3, 1)
+    matrix = torch.argmax(matrix, dim=-1)
+    matrix = torch.nn.functional.one_hot(matrix, num_classes=num_classes)
+    matrix = matrix.permute(0, 3, 1, 2)
+    return matrix
+
+
+#--- I'm using just categorical cross_entropy for now
+class Loss(nn.Module):
+  def __init__(self):
+    super().__init__()
+
+  def forward(self, predictions, targets):
+    # predictions --> (B, #C, H, W) unnormalized
+    # targets     --> (B, #C, H, W) one-hot encoded
+    targets = torch.argmax(targets, dim=1)
+    pixel_loss = F.cross_entropy(predictions, targets, reduction="mean")
+
+    return pixel_loss
+  
+  
+class Metric(nn.Module):
+    def __init__(self, num_classes=3, smooth=1e-6, use_dice=False):
+        super().__init__()
+        self.num_classes = num_classes
+        self.smooth      = smooth
+        self.use_dice    = use_dice
+
+    def forward(self, predictions, targets):
+        # predictions  --> (B, #C, H, W) unnormalized
+        # targets      --> (B, #C, H, W) one-hot encoded
+
+        # Converting unnormalized predictions into one-hot encoded across channels.
+        # Shape: (B, #C, H, W)
+        predictions = convert_2_onehot(predictions, num_classes=self.num_classes) # one hot encoded
+        metric = intermediate_metric_calculation(predictions, targets, use_dice=self.use_dice, smooth=self.smooth)
+
+        # Compute the mean over the remaining axes (batch and classes). Shape: Scalar
+        return metric
+
+
+def get_default_device():
+    return torch.device('cuda' if torch.cuda.is_available() else 'cpu')
+
+
+def readyBaseModel():
+
+    #--- prep model conditions
+    device = get_default_device()
+    model = prepare_model(backbone_model=backbone_model_name, num_classes=NUM_CLASSES)
+
+    metric_name = "iou"
+    use_dice = (True if metric_name == "dice" else False)
+    metric_fn = Metric(num_classes=NUM_CLASSES, use_dice=use_dice).to(device)
+    loss_fn   = Loss().to(device)
+    optimizer = torch.optim.Adam(model.parameters(), lr=0.0001)
+
+    return model
+
+
+def readyModelWithWeights(mdlBase):
+    print("TRACE:  loading model with weights ... ", model_path)    
+    mdlBase.load_state_dict(torch.load(model_path, map_location=torch.device('cpu')))
+    model_with_weights = mdlBase
+    model_with_weights.eval()
+    return model_with_weights
+
+
+class SegmentationModelOutputWrapper(torch.nn.Module):
+  def __init__(self, model):
+      super(SegmentationModelOutputWrapper, self).__init__()
+      self.model = model
+
+  def forward(self, x):
+    return self.model(x)["out"]
+  
+
+def readyModelWithXAI(mdlWeighted):
+    model_xai = SegmentationModelOutputWrapper(mdlWeighted)
+
+    model_xai.eval()
+    model_xai.to('cpu')
+    return model_xai
+
+
+#--- demo:  process a single file for validation/demo
+def val_filToTensor(strPth_fil):
+  img_fil = Image.open(strPth_fil)
+  img_fil = img_fil.convert("RGB")
+  img_fil = np.asarray(img_fil)/255
+  return to_tensor(img_fil).unsqueeze(0)
+
+
+#--- TODO demo:  process a batch of files for validation/demo
+def val_aryToTensor(pth_fil, ary_fils):
+  aryTensor = []
+  for str_filName in ary_fils:
+    aryTensor.append(val_filToTensor(pth_fil, str_filName))
+  return aryTensor
+
+
+def predXai_tile(mdl_xai, strPth_tileRaw):
+    #--- run a prediction for a single 
+    print("TRACE:  get tensor from single file ... ", strPth_tileRaw)
+    val_tensorFil = val_filToTensor(strPth_tileRaw)
+    val_tensorBatch = val_tensorFil
+
+    print("TRACE:  get mdl_xai prediction ...")
+    output = mdl_xai(val_tensorBatch.float().to('cpu'))
+
+    print("TRACE:  predXai_tile return ...")
+    return output, val_tensorBatch
+
+
+class SemanticSegmentationTarget:
+  def __init__(self, category, mask):
+    self.category = category
+    self.mask = torch.from_numpy(mask)
+    if torch.cuda.is_available():
+        self.mask = self.mask.cuda()
+
+  def __call__(self, model_output):
+    return (model_output[self.category, :, : ] * self.mask).sum()
+  
+
+def predGradCam_tile(output_xaiPred, mdl_xai, val_image_batch):
+    print("TRACE:  predGradCam initialize ...")
+    cam_img_bg = []
+    cam_img_wt = []
+    cam_img_vt = []
+
+    sem_classes = ['__background__', 'whole_tumor', 'viable_tumor']
+    sem_class_to_idx = {cls: idx for (idx, cls) in enumerate(sem_classes)}
+
+    argmax_mask = torch.argmax(output_xaiPred, dim=1)
+    argmax_mask_np = argmax_mask.cpu().squeeze().numpy()
+    preds = argmax_mask_np
+
+    seg_mask = preds
+    bg_category = sem_class_to_idx["__background__"]
+    bg_mask_float = np.float32(seg_mask == bg_category)
+    wt_category = sem_class_to_idx["whole_tumor"]
+    wt_mask_float = np.float32(seg_mask == wt_category)
+    vt_category = sem_class_to_idx["viable_tumor"]
+    vt_mask_float = np.float32(seg_mask == vt_category)
+
+    target_layers = [mdl_xai.model.backbone.layer4]
+
+    for i in range(len(val_image_batch)):
+        rgb_img = np.float32(val_image_batch[i].permute(1, 2, 0))
+        rgb_tensor = val_image_batch[i].unsqueeze(0).float()
+
+        print("TRACE:  process the background ...")
+        targets = [SemanticSegmentationTarget(bg_category, bg_mask_float[i])]
+        with GradCAM(model=mdl_xai,
+                    target_layers=target_layers,
+                    use_cuda=torch.cuda.is_available()) as cam:
+
+                    grayscale_cam = cam(input_tensor = rgb_tensor,
+                                        targets = targets)[0, :]
+                    cam_img_bg.append(show_cam_on_image(rgb_img, grayscale_cam, use_rgb=True))
+
+        print("TRACE:  process whole tumors ...")
+        targets = [SemanticSegmentationTarget(wt_category, wt_mask_float[i])]
+        with GradCAM(model=mdl_xai,
+                    target_layers=target_layers,
+                    use_cuda=torch.cuda.is_available()) as cam:
+
+                    grayscale_cam = cam(input_tensor = rgb_tensor,
+                                        targets = targets)[0, :]
+                    cam_img_wt.append(show_cam_on_image(rgb_img, grayscale_cam, use_rgb=True))
+
+        print("TRACE:  process viable tumors ...")
+        targets = [SemanticSegmentationTarget(vt_category, vt_mask_float[i])]
+        with GradCAM(model=mdl_xai,
+                    target_layers=target_layers,
+                    use_cuda=torch.cuda.is_available()) as cam:
+
+                    grayscale_cam = cam(input_tensor = rgb_tensor,
+                                        targets = targets)[0, :]
+                    cam_img_vt.append(show_cam_on_image(rgb_img, grayscale_cam, use_rgb=True))
+    
+    return cam_img_bg, cam_img_wt, cam_img_vt

uix/pages/lit_home.py

@@ -0,0 +1,32 @@
+#--- about page
+import streamlit as st
+
+description = "Home"
+def run():
+
+    print("\nINFO (lit_home.run)  loading ", description, " page ...") 
+
+
+    st.markdown('### Home')
+    st.markdown('### Omdena Saudi:  Liver HCC Diagnosis with XAI')
+    st.markdown('#### Chapter Lead:  Dr. Shai')
+    st.markdown('\
+        <background> \
+         ')
+    
+    st.markdown('\
+        <basis> \
+         ')
+    
+    st.markdown('\
+        <claim> \
+         ')
+
+    st.markdown(
+        """
+
+            Home page
+        
+        """,
+            unsafe_allow_html=True,
+        )

uix/pages/lit_qaConfigCheck.py

@@ -0,0 +1,88 @@
+#--- about page
+import streamlit as st
+import sys, os
+import pandas as pd
+
+import lib.utils as libUtils
+
+
+description = "QA:  Config Check"
+def run():
+
+    print("\nINFO (lit_config.run)  loading ", description, " page ...") 
+
+    #--- 
+    #st.experimental_memo.clear()            #--- try to clear cache each time this page is hit
+    #st.cache_data.clear()
+
+    st.markdown('### Configuration Check')
+
+    #--- check that base folders exist
+    #--- list raw WSIs
+    lstWSI = os.listdir(libUtils.pth_dtaWsi + "raw/")
+    print("TRACE: ", lstWSI)
+    st.dataframe(
+        pd.DataFrame({"Raw WSI":  lstWSI,}),
+        use_container_width=True
+    )
+
+    #--- list raw Tiles
+    lstTiles = os.listdir(libUtils.pth_dtaTiles + "raw/")
+    print("TRACE: ", lstTiles)
+    st.dataframe(
+        pd.DataFrame({"Raw Tiles":  lstTiles,}),
+        use_container_width=True
+    )
+
+    #--- list raw demo Tiles
+    lstDemo = os.listdir(libUtils.pth_dtaDemoTiles + "raw/")
+    print("TRACE: ", lstDemo)
+    st.dataframe(
+        pd.DataFrame({"Raw Demo Tiles":  lstDemo,}),
+        use_container_width=True
+    )
+
+
+    st.markdown('''
+        <style>
+            [data-testid="stMarkdownContainer"] ul{
+                list-style-position: inside;
+            }
+        </style>
+        ''', unsafe_allow_html=True)
+    
+
+#    st.markdown(
+        # st.footer(
+        # """
+        #     Configuration Check page
+        # """,
+        #     unsafe_allow_html=True,
+        # )
+    
+    cssFooter="""
+        <style>
+            a:link, 
+            a:visited{
+                color: blue;
+                background-color: transparent;
+                text-decoration: underline;
+            }
+            a:hover,  a:active {
+                color: red;
+                background-color: transparent;
+                text-decoration: underline;
+                }
+            .footer {
+                position: fixed;
+                left: 0; bottom: 0; width: 100%;
+                background-color: white;
+                color: black;
+                text-align: center;
+            }
+        </style>
+        <div class="footer">
+            <p>Configuration Check Page</p>
+        </div>
+    """
+    st.markdown(cssFooter, unsafe_allow_html=True)

util_dockerPreRun.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+
+#--- Note:  this file is designed to run locally as well as within docker to prep the environment
+#--- for volume initialization; ensure folders are in place; assume:  we are in the /app folder
+mkdir -p data/demo_tiles/raw
+mkdir -p data/tiles/raw data/tiles/pred data/tiles/grad_bg data/tiles/grad_wt data/tiles/grad_vt
+mkdir -p data/wsi/raw
+
+
+<<blockComment 
+- the binary model is stored as split files named mdl_nn
+- this is done to ensure that the model can be stored within gitHub
+- the split model is recreated on docker container startup using the cat command
+blockComment
+
+#--- recreate single model file from its parts, stored within a specific model version folder
+./bin/models/util_joinModel.sh './bin/models/deeplabv3*vhflip30/model_a*' ./bin/models/model.pth
+
+#--- run streamlit/fastapi
+./util_startLocal_streamlitFastApi.sh

util_startLocal_streamlitFastApi.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+#--- Note:  this file is designed to run locally and within docker to prep the environment
+#--- for volume initialization; ensure folders are in place; assume:  we are in the /app folder
+#mkdir -p data/demo_tiles/raw
+#mkdir -p data/tiles/raw data/tiles/pred data/tiles/grad_bg data/tiles/grad_wt data/tiles/grad_vt
+#mkdir -p data/wsi/raw
+
+#--- for streamlit;  external 49400;  internal 39400
+echo "INFO:  starting streamlit ..."
+streamlit run app.py --server.port=39400 --server.maxUploadSize=2000 &
+
+#--- for fastapi;  external 49500;  internal 39500
+echo "INFO:  starting fastapi ..."
+uvicorn main:app --reload --workers 1 --host 0.0.0.0 --port 39500 &
+
+#--- wait for any process to exit
+wait -n
+
+#--- Exit with status of process that exited first
+exit $?