3701809bbf
README with prerequisites, install steps, usage guide, supported formats, project structure, and API reference.
154 lines
4.4 KiB
Markdown
154 lines
4.4 KiB
Markdown
# CMM Report Analyzer
|
|
|
|
A FastAPI web application that parses CMM (Coordinate Measuring Machine) inspection reports, computes SPC metrics, generates interactive charts, and provides AI-powered quality summaries.
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.11 or higher
|
|
- pip (comes with Python)
|
|
- Git
|
|
|
|
## Setup
|
|
|
|
### 1. Clone the repository
|
|
|
|
```bash
|
|
git clone https://git.deathstar-home.one/chrisryn/cmm-report-analyzer.git
|
|
cd cmm-report-analyzer
|
|
```
|
|
|
|
### 2. Create a virtual environment
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
```
|
|
|
|
Activate it:
|
|
|
|
```bash
|
|
# Linux / macOS
|
|
source .venv/bin/activate
|
|
|
|
# Windows (PowerShell)
|
|
.venv\Scripts\Activate.ps1
|
|
|
|
# Windows (CMD)
|
|
.venv\Scripts\activate.bat
|
|
```
|
|
|
|
### 3. Install dependencies
|
|
|
|
```bash
|
|
pip install -e .
|
|
```
|
|
|
|
To also install dev/test dependencies:
|
|
|
|
```bash
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
### 4. Configure environment variables
|
|
|
|
Copy the example file:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` with your values:
|
|
|
|
| Variable | Description | Required |
|
|
|---|---|---|
|
|
| `AZURE_OPENAI_ENDPOINT` | Your Azure OpenAI resource URL (e.g. `https://your-resource.openai.azure.com`) | No |
|
|
| `AZURE_OPENAI_API_KEY` | Your Azure OpenAI API key | No |
|
|
| `AZURE_OPENAI_DEPLOYMENT` | Deployment name (default: `gpt-4o`) | No |
|
|
| `AZURE_OPENAI_API_VERSION` | API version (default: `2024-10-21`) | No |
|
|
|
|
> **Note:** The Azure OpenAI settings are optional. Without them, the app will still work fully -- it will generate a rule-based fallback summary instead of an AI-powered one.
|
|
|
|
### 5. Run the app
|
|
|
|
```bash
|
|
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
Then open your browser to **http://localhost:8000**.
|
|
|
|
### 6. Run tests
|
|
|
|
```bash
|
|
pytest tests/ -v
|
|
```
|
|
|
|
## Usage
|
|
|
|
1. Open the web UI at `http://localhost:8000`
|
|
2. Drag and drop (or browse for) one or more CMM report files
|
|
3. Supported file types: `.pdf`, `.xlsx`, `.xls`, `.csv`
|
|
4. Click **Analyze Files**
|
|
5. View results including:
|
|
- **AI/rule-based quality summary** -- pass/fail assessment, features of concern, corrective actions
|
|
- **SPC metrics table** -- Cp, Cpk, Pp, Ppk, control limits, out-of-spec counts per feature
|
|
- **Interactive charts** -- distribution histograms, control charts, capability bar chart (powered by Plotly)
|
|
- **Full measurement details** -- expandable table with per-measurement tolerance status
|
|
|
|
## Supported Report Formats
|
|
|
|
The parsers use fuzzy column-name matching, so your files don't need exact header names. The app looks for columns matching these patterns:
|
|
|
|
| Field | Recognized headers (partial match) |
|
|
|---|---|
|
|
| Feature name | feat, char, dimen, label, id, name, item |
|
|
| Nominal | nom, target, blueprint, print |
|
|
| Actual | actual, meas, value, result, reading |
|
|
| Tolerance + | tol+, upper tol, usl, pos tol |
|
|
| Tolerance - | tol-, lower tol, lsl, neg tol |
|
|
| Deviation | dev, diff, error, delta |
|
|
|
|
For PDF files, the parser also extracts metadata such as part number, serial number, inspection date, program, and operator from the report text.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
app/
|
|
main.py FastAPI entrypoint
|
|
config.py Settings (.env loading)
|
|
routers/
|
|
upload.py POST /api/upload
|
|
results.py GET /api/results/{batch_id}
|
|
parsers/
|
|
models.py MeasurementRecord, ParsedReport
|
|
base.py Abstract parser, fuzzy column matching
|
|
excel_parser.py Excel/CSV parser (pandas + openpyxl)
|
|
pdf_parser.py PDF parser (pdfplumber)
|
|
analysis/
|
|
spc.py SPC calculations (Cp/Cpk/Pp/Ppk, Shapiro-Wilk)
|
|
charts.py Plotly chart generation
|
|
ai/
|
|
summarizer.py Azure OpenAI summary with fallback
|
|
services/
|
|
batch.py Orchestration pipeline (parse -> SPC -> charts -> summary)
|
|
static/
|
|
index.html Web UI
|
|
css/style.css Styles
|
|
js/app.js Frontend logic
|
|
tests/
|
|
test_api.py API integration tests
|
|
test_parsers.py Parser unit tests
|
|
test_spc.py SPC calculation tests
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
| Method | Path | Description |
|
|
|---|---|---|
|
|
| `POST` | `/api/upload` | Upload one or more CMM report files. Returns `{ batch_id, file_count }`. |
|
|
| `GET` | `/api/results/{batch_id}` | Retrieve analysis results for a batch. Returns SPC metrics, charts, and summary. |
|
|
|
|
## Notes
|
|
|
|
- Results are stored **in memory only** and are lost when the server restarts.
|
|
- Maximum upload size is 50 MB per file (configurable via `MAX_UPLOAD_MB` env var).
|
|
- The app accepts multiple files in a single upload and processes them concurrently.
|