Week 3

.github/workflows/python-tests.yaml

@@ -0,0 +1,23 @@
+name: Python tests
+
+on:
+  push:
+    branches: [main, week-1, week-2, week-3]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install package and test tools
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Run unit tests
+        run: pytest

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*$py.class
+venv/
+env/
+.venv/
+.DS_Store

docs/.ipynb_checkpoints/report-checkpoint.ipynb

@@ -0,0 +1,97 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "73620923-8165-4d80-a81a-cb768294cc6f",
+   "metadata": {},
+   "source": [
+    "Week 3 Assignment: Knitting Pattern Calculator Project Report\n",
+    "\n",
+    "1. Project Overview\n",
+    "Knitting a custom sweater from the top down requires translating physical body measurements into a discrete grid of stitches and rows based on a individual knitting gauge. Manual conversion often leads to structural math errors. Furthermore, knitters wanting to incorporate multi-colored intarsia or stranded motifs (\"alpha patterns\") must manually map those pixel charts onto their specific garment dimensions, which is a slow and error-prone process.\n",
+    "\n",
+    "This project automates both tasks. It pairs a Streamlit web interface with a specialized Python backend that accepts pixel-based alpha patterns, calculates necessary fabric grading, and automatically generates a matching color chart, text instructions, and a visual preview of the finalized piece."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fea57056-3a79-4bde-a173-4e34421c522b",
+   "metadata": {},
+   "source": [
+    "2. Software Architecture\n",
+    "The software uses the standard Python src/ layout to isolate core business and graphical logic from the presentation layer.\n",
+    "knitting_pattern/\n",
+    "├── src/\n",
+    "│   ├── knitting_pattern/\n",
+    "│   │   ├── __init__.py          # Exposes core calculation functions\n",
+    "│   │   ├── app.py               # Streamlit web application interface\n",
+    "│   │   ├── math_engine.py       # Math logic, matrix grid creation, and chart operations\n",
+    "│   │   └── image_engine.py      # Visualization logic, plotting chart and recognizing alpha patterns\n",
+    "│   └── tests/\n",
+    "│       ├── test_image_engine.py\n",
+    "│       └── test_math_engine.py  \n",
+    "Stitch and Row Allocation: The engine converts user dimensions (in centimeters) to absolute integers. \n",
+    "It uses ceiling rounding (math.ceil) since a knitter cannot execute a partial stitch. The underlying formula is:\n",
+    "stitches = [{width (cm)} * {stitch gauge} / 10)]\n",
+    "\n",
+    "Grid Canvas Representation: The backend models the fabric as a two-dimensional grid (nested lists or arrays). Unoccupied background fabric is initialized to 0.\n",
+    "Alpha Pattern Integration: The system reads pixel-based assets representing the alpha design. It maps these coordinates directly onto the sweater grid, reassigning target cells from background 0 to specific integer color IDs (e.g., 1, 2, 3). This acts as the layout for the color chart."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c6508f58-97f2-4e02-ad03-a1d7d445bfcf",
+   "metadata": {},
+   "source": [
+    "3. Current Implementation: Drop-Shoulder Top-Down Construction\n",
+    "The application currently models a traditional drop-shoulder construction, worked from the top down.\n",
+    "\n",
+    "Back Panel Cast-On: The program calculates the back shoulder width and establishes the upper grid boundary.\n",
+    "\n",
+    "Short-Row Contour Carving: To create an ergonomic shoulder slope and back-neck contour, the engine calculates short-row steps. It modifies the fabric matrix by marking unknitted coordinates as dead space (-1) while keeping active channels at 0. This allows the application to accurately trace variable-row knitting before mapping the alpha motif.\n",
+    "\n",
+    "Straight Body Extension: Once short rows are complete, the body grid expands downward in straight, uniform columns to form the classic drop-shoulder silhouette."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b8f45f76-aedd-47be-b76e-461a696b3812",
+   "metadata": {},
+   "source": [
+    "4. Current Limitations and Future Expansion\n",
+    "While the drop-shoulder math and base grid generation are operational, our development roadmap highlights three areas of expansion:\n",
+    "\n",
+    "High-Contrast Visualizations and Text Instructions\n",
+    "Problem: The current output shows a basic matrix visualization. It works for debugging but does not generate clear, printable charts or row-by-row text patterns for the user.\n",
+    "\n",
+    "Solution: Upgrade the visualization component with customized, high-contrast color maps to output downloadable PDF color charts. Concurrently, write a translation loop that reads the matrix rows and outputs automated text instructions (e.g., \"Row 12: K10 Turn; Row 13: P to end of row\").\n",
+    "\n",
+    "Geometric Silhouette Expansion\n",
+    "Problem: The system is limited to drop-shoulder shapes, which utilize straight armhole paths and simple rectangular panels.\n",
+    "\n",
+    "Solution: Expand the mathematical backend to calculate complex raglan lines and set-in sleeve caps. This requires developing dynamic decrease formulas to scale diagonal stitch lines across the grid canvas while maintaining the integrity of the centered alpha patterns."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python [conda env:base] *",
+   "language": "python",
+   "name": "conda-base-py"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/report.ipynb

@@ -0,0 +1,97 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "73620923-8165-4d80-a81a-cb768294cc6f",
+   "metadata": {},
+   "source": [
+    "Week 3 Assignment: Knitting Pattern Calculator Project Report\n",
+    "\n",
+    "1. Project Overview\n",
+    "Knitting a custom sweater from the top down requires translating physical body measurements into a discrete grid of stitches and rows based on a individual knitting gauge. Manual conversion often leads to structural math errors. Furthermore, knitters wanting to incorporate multi-colored intarsia or stranded motifs (\"alpha patterns\") must manually map those pixel charts onto their specific garment dimensions, which is a slow and error-prone process.\n",
+    "\n",
+    "This project automates both tasks. It pairs a Streamlit web interface with a specialized Python backend that accepts pixel-based alpha patterns, calculates necessary fabric grading, and automatically generates a matching color chart, text instructions, and a visual preview of the finalized piece."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "fea57056-3a79-4bde-a173-4e34421c522b",
+   "metadata": {},
+   "source": [
+    "2. Software Architecture\n",
+    "The software uses the standard Python src/ layout to isolate core business and graphical logic from the presentation layer.\n",
+    "knitting_pattern/\n",
+    "├── src/\n",
+    "│   ├── knitting_pattern/\n",
+    "│   │   ├── __init__.py          # Exposes core calculation functions\n",
+    "│   │   ├── app.py               # Streamlit web application interface\n",
+    "│   │   ├── math_engine.py       # Math logic, matrix grid creation, and chart operations\n",
+    "│   │   └── image_engine.py      # Visualization logic, plotting chart and recognizing alpha patterns\n",
+    "│   └── tests/\n",
+    "│       ├── test_image_engine.py\n",
+    "│       └── test_math_engine.py  \n",
+    "Stitch and Row Allocation: The engine converts user dimensions (in centimeters) to absolute integers. \n",
+    "It uses ceiling rounding (math.ceil) since a knitter cannot execute a partial stitch. The underlying formula is:\n",
+    "stitches = [{width (cm)} * {stitch gauge} / 10)]\n",
+    "\n",
+    "Grid Canvas Representation: The backend models the fabric as a two-dimensional grid (nested lists or arrays). Unoccupied background fabric is initialized to 0.\n",
+    "Alpha Pattern Integration: The system reads pixel-based assets representing the alpha design. It maps these coordinates directly onto the sweater grid, reassigning target cells from background 0 to specific integer color IDs (e.g., 1, 2, 3). This acts as the layout for the color chart."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c6508f58-97f2-4e02-ad03-a1d7d445bfcf",
+   "metadata": {},
+   "source": [
+    "3. Current Implementation: Drop-Shoulder Top-Down Construction\n",
+    "The application currently models a traditional drop-shoulder construction, worked from the top down.\n",
+    "\n",
+    "Back Panel Cast-On: The program calculates the back shoulder width and establishes the upper grid boundary.\n",
+    "\n",
+    "Short-Row Contour Carving: To create an ergonomic shoulder slope and back-neck contour, the engine calculates short-row steps. It modifies the fabric matrix by marking unknitted coordinates as dead space (-1) while keeping active channels at 0. This allows the application to accurately trace variable-row knitting before mapping the alpha motif.\n",
+    "\n",
+    "Straight Body Extension: Once short rows are complete, the body grid expands downward in straight, uniform columns to form the classic drop-shoulder silhouette."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b8f45f76-aedd-47be-b76e-461a696b3812",
+   "metadata": {},
+   "source": [
+    "4. Current Limitations and Future Expansion\n",
+    "While the drop-shoulder math and base grid generation are operational, our development roadmap highlights three areas of expansion:\n",
+    "\n",
+    "High-Contrast Visualizations and Text Instructions\n",
+    "Problem: The current output shows a basic matrix visualization. It works for debugging but does not generate clear, printable charts or row-by-row text patterns for the user.\n",
+    "\n",
+    "Solution: Upgrade the visualization component with customized, high-contrast color maps to output downloadable PDF color charts. Concurrently, write a translation loop that reads the matrix rows and outputs automated text instructions (e.g., \"Row 12: K10 Turn; Row 13: P to end of row\").\n",
+    "\n",
+    "Geometric Silhouette Expansion\n",
+    "Problem: The system is limited to drop-shoulder shapes, which utilize straight armhole paths and simple rectangular panels.\n",
+    "\n",
+    "Solution: Expand the mathematical backend to calculate complex raglan lines and set-in sleeve caps. This requires developing dynamic decrease formulas to scale diagonal stitch lines across the grid canvas while maintaining the integrity of the centered alpha patterns."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python [conda env:base] *",
+   "language": "python",
+   "name": "conda-base-py"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.13.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

pyproject.toml

@@ -3,7 +3,7 @@ requires = ["hatchling >= 1.26"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
-packages = ["alpha_calc"]
+packages = ["src/knitting_pattern"]
 
 [project]
 name = "knitting_pattern"
@@ -14,12 +14,25 @@ authors = [
 description = "Kitting pattern calculator tool for my programming course"
 readme = "README.md"
 requires-python = ">=3.9"
+dependencies = [
+    "numpy",
+    "Pillow",
+    "streamlit",
+    "matplotlib"
+]
 classifiers = [
     "Programming Language :: Python :: 3",
     "Operating System :: OS Independent",
 ]
-license = "MIT"
-license-files = ["LICEN[CS]E*"]
+license = {text = "MIT"}
+
+[project.optional-dependencies]
+dev = [
+    "pytest",
+]
 
 [project.urls]
 Homepage = "https://github.com/Programming-The-Next-Step-2026/knitting_pattern.git"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

src/knitting_pattern/__init__.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Created on Sun May 17 20:22:07 2026
+
+@author: kasteivanauskaite
+"""
+
+from .example import add, calculate_mean
+
+# engine/__init__.py
+
+# This exposes these specific functions to the rest of your app
+from .math_engine import (
+    calculate_stitches, calculate_rows, calculate_garment_dimensions,
+    calculate_top_down_shoulder_shaping, generate_panel_grid, apply_top_down_mountains_to_grid,
+    calculate_back_neck_shaping, apply_back_short_rows_to_grid 
+)
+
+# Expose Image Engine Functions
+from .image_engine import (
+    get_hardcoded_heart,
+    scale_pattern_matrix_integer,
+    overlay_pattern_on_grid,
+    generate_chart_image
+)