SudokuSolver.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "Using TensorFlow backend.\n"
     ]
    }
   ],
   "source": [
    "import numpy as np\n",
    "\n",
    "from __future__ import print_function\n",
    "import numpy as np\n",
    "from ortools.sat.python import cp_model\n",
    "\n",
    "import sys\n",
    "import keras\n",
    "from keras import Sequential\n",
    "from keras import backend as bck\n",
    "from keras.datasets import mnist"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Solver Class\n",
    "This class contains a simple solver written in Or-Tools. Constraint programming used in here is very fast and (i hope) easy to understand.\n",
    "\n",
    "Constructor contains data about sudoku - grid size, cell size and two or-tools objects:\n",
    "- model\n",
    "- solver\n",
    "Both of those are used to find the solution. There is no need for more complicated solver than a basic CpSolver.\n",
    "\n",
    "- get_values - reads grid given to class (read from image) and inserting to solution.\n",
    "- printer - just a print-to-console class.\n",
    "- solve() - ...solving. Contains proper constraints for sudoku."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "# I am a simple solver.\n",
    "class Solver:\n",
    "    def __init__(self):\n",
    "        self.model = cp_model.CpModel()\n",
    "        self.solver = cp_model.CpSolver()\n",
    "        self.grid_size = 9\n",
    "        self.cell_size = 3\n",
    "\n",
    "    def get_values(self, solution, original_grid):\n",
    "        for row in range(self.grid_size):\n",
    "            for column in range(self.grid_size):\n",
    "                if original_grid[row, column] == 0:\n",
    "                    solution[row, column] = self.model.NewIntVar(1, 9, '(%i,%i)' % (row, column))\n",
    "                else:\n",
    "                    solution[row, column] = self.model.NewConstant(int(original_grid[row, column]))\n",
    "        return solution\n",
    "\n",
    "    def printer(self, solution):\n",
    "        for i in range(self.grid_size):\n",
    "            if i % 3 == 0:\n",
    "                print(\"\\n\")\n",
    "            for j in range(self.grid_size):\n",
    "                if j % 3 == 0 and j != 0:\n",
    "                    print(\" \", end = \" \")\n",
    "                print(self.solver.Value(solution[i,j]), end=\" \")\n",
    "            print()\n",
    "\n",
    "    def solve(self, grid):\n",
    "        solutions = {}\n",
    "\n",
    "        # Get ints from grid\n",
    "        solutions = self.get_values(solutions, grid)\n",
    "\n",
    "        ##---CONSTRAINTS---\n",
    "        # Horizontals\n",
    "        for row in range(self.grid_size):\n",
    "            line_horizontal = []\n",
    "            for column in range(self.grid_size):\n",
    "                line_horizontal.append(solutions[row, column])\n",
    "            self.model.AddAllDifferent(line_horizontal)\n",
    "\n",
    "        # Verticals\n",
    "        for column in range(self.grid_size):\n",
    "            line_vertical = []\n",
    "            for row in range(self.grid_size):\n",
    "                line_vertical.append(solutions[row, column])\n",
    "            self.model.AddAllDifferent(line_vertical)\n",
    "\n",
    "        # Squares\n",
    "        for row_idx in range(0, self.grid_size, self.cell_size):\n",
    "            for col_idx in range(0, self.grid_size, self.cell_size):\n",
    "                self.model.AddAllDifferent([solutions[row_idx + row, column] for column in range(col_idx, (col_idx + self.cell_size)) \n",
    "                                            for row in range(self.cell_size)])\n",
    "\n",
    "        # Solve model\n",
    "        status = self.solver.Solve(self.model)\n",
    "        if status != cp_model.INFEASIBLE:\n",
    "            self.printer(solutions)\n",
    "        else:\n",
    "            print(\"Impossible to solve, try again.\")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Training\n",
    "The class below is handling MNIST dataset and image adjustments, not much more to say."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "# I am a training reader.\n",
    "import cv2\n",
    "class TrainingReader:\n",
    "    def __init__(self):\n",
    "        self.num_classes = 10\n",
    "        self.size_rows = 28\n",
    "        self.size_cols = 28\n",
    "        self.input_shape = ()\n",
    "        self.x_test = []\n",
    "        self.x_train = []\n",
    "        self.y_test = []\n",
    "        self.y_train = []\n",
    "\n",
    "    def adjust_images(self, x_train, x_test):\n",
    "        # Shape adjustment\n",
    "        x_train = np.reshape(x_train, (-1,28,28,1))\n",
    "        x_test = np.reshape(x_test ,(-1,28,28,1))\n",
    "        # Type adjustment\n",
    "        x_train = x_train / 16\n",
    "        x_test = x_test / 16\n",
    "        return x_train, x_test\n",
    "\n",
    "    def create_labels(self, y_original):\n",
    "        y_new = keras.utils.to_categorical(y_original)\n",
    "        return y_new\n",
    "\n",
    "    def read_mnist(self):\n",
    "        try:\n",
    "            (x_train, y_train), (x_test, y_test) = mnist.load_data()\n",
    "            self.x_train, self.x_test = self.adjust_images(x_train, x_test)\n",
    "            self.y_train = self.create_labels(y_train)\n",
    "            self.y_test = self.create_labels(y_test)\n",
    "            print(\"MNIST dataset was read correctly!\")\n",
    "        except:\n",
    "            print(\"Unexpected error in TrainingReader: \", sys.exc_info()[0])\n",
    "            raise\n",
    "        "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Model class\n",
    "Model was created according to this article: https://www.kaggle.com/cdeotte/how-to-choose-cnn-architecture-mnist"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "MNIST dataset was read correctly!\n"
     ]
    }
   ],
   "source": [
    "from sklearn import svm\n",
    "import sys\n",
    "from sklearn import datasets, svm, metrics\n",
    "from sklearn.model_selection import train_test_split\n",
    "\n",
    "trainer = TrainingReader()\n",
    "trainer.read_mnist()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Model: \"sequential_1\"\n",
      "_________________________________________________________________\n",
      "Layer (type)                 Output Shape              Param #   \n",
      "=================================================================\n",
      "conv2d_1 (Conv2D)            (None, 26, 26, 32)        320       \n",
      "_________________________________________________________________\n",
      "batch_normalization_1 (Batch (None, 26, 26, 32)        128       \n",
      "_________________________________________________________________\n",
      "conv2d_2 (Conv2D)            (None, 24, 24, 32)        9248      \n",
      "_________________________________________________________________\n",
      "batch_normalization_2 (Batch (None, 24, 24, 32)        128       \n",
      "_________________________________________________________________\n",
      "conv2d_3 (Conv2D)            (None, 12, 12, 32)        25632     \n",
      "_________________________________________________________________\n",
      "batch_normalization_3 (Batch (None, 12, 12, 32)        128       \n",
      "_________________________________________________________________\n",
      "dropout_1 (Dropout)          (None, 12, 12, 32)        0         \n",
      "_________________________________________________________________\n",
      "conv2d_4 (Conv2D)            (None, 10, 10, 64)        18496     \n",
      "_________________________________________________________________\n",
      "batch_normalization_4 (Batch (None, 10, 10, 64)        256       \n",
      "_________________________________________________________________\n",
      "conv2d_5 (Conv2D)            (None, 8, 8, 64)          36928     \n",
      "_________________________________________________________________\n",
      "batch_normalization_5 (Batch (None, 8, 8, 64)          256       \n",
      "_________________________________________________________________\n",
      "conv2d_6 (Conv2D)            (None, 4, 4, 64)          102464    \n",
      "_________________________________________________________________\n",
      "batch_normalization_6 (Batch (None, 4, 4, 64)          256       \n",
      "_________________________________________________________________\n",
      "dropout_2 (Dropout)          (None, 4, 4, 64)          0         \n",
      "_________________________________________________________________\n",
      "flatten_1 (Flatten)          (None, 1024)              0         \n",
      "_________________________________________________________________\n",
      "dense_1 (Dense)              (None, 128)               131200    \n",
      "_________________________________________________________________\n",
      "batch_normalization_7 (Batch (None, 128)               512       \n",
      "_________________________________________________________________\n",
      "dropout_3 (Dropout)          (None, 128)               0         \n",
      "_________________________________________________________________\n",
      "dense_2 (Dense)              (None, 10)                1290      \n",
      "=================================================================\n",
      "Total params: 327,242\n",
      "Trainable params: 326,410\n",
      "Non-trainable params: 832\n",
      "_________________________________________________________________\n"
     ]
    }
   ],
   "source": [
    "import tensorflow as tf\n",
    "from tensorflow import keras\n",
    "from keras import Sequential\n",
    "from keras.layers import Dense, Dropout, Activation, Flatten\n",
    "from keras.layers import Conv2D, MaxPooling2D, BatchNormalization\n",
    "\n",
    "model = Sequential()\n",
    "\n",
    "model.add(Conv2D(32,kernel_size=3,activation='relu',input_shape=(28,28,1)))\n",
    "model.add(BatchNormalization())\n",
    "model.add(Conv2D(32,kernel_size=3,activation='relu'))\n",
    "model.add(BatchNormalization())\n",
    "model.add(Conv2D(32,kernel_size=5,strides=2,padding='same',activation='relu'))\n",
    "model.add(BatchNormalization())\n",
    "model.add(Dropout(0.4))\n",
    "\n",
    "model.add(Conv2D(64,kernel_size=3,activation='relu'))\n",
    "model.add(BatchNormalization())\n",
    "model.add(Conv2D(64,kernel_size=3,activation='relu'))\n",
    "model.add(BatchNormalization())\n",
    "model.add(Conv2D(64,kernel_size=5,strides=2,padding='same',activation='relu'))\n",
    "model.add(BatchNormalization())\n",
    "model.add(Dropout(0.4))\n",
    "\n",
    "model.add(Flatten())\n",
    "model.add(Dense(128, activation='relu'))\n",
    "model.add(BatchNormalization())\n",
    "model.add(Dropout(0.4))\n",
    "model.add(Dense(10, activation='softmax'))\n",
    "\n",
    "model.compile(optimizer=\"adam\", loss=\"categorical_crossentropy\", metrics=[\"accuracy\"])\n",
    "model.summary()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Epoch 1/10\n",
      "60000/60000 [==============================] - 227s 4ms/step - loss: 0.1860 - accuracy: 0.9433\n",
      "Epoch 2/10\n",
      "60000/60000 [==============================] - 207s 3ms/step - loss: 0.0675 - accuracy: 0.9796\n",
      "Epoch 3/10\n",
      "60000/60000 [==============================] - 201s 3ms/step - loss: 0.0569 - accuracy: 0.9829\n",
      "Epoch 4/10\n",
      "60000/60000 [==============================] - 184s 3ms/step - loss: 0.0471 - accuracy: 0.9860\n",
      "Epoch 5/10\n",
      "60000/60000 [==============================] - 189s 3ms/step - loss: 0.0426 - accuracy: 0.9874\n",
      "Epoch 6/10\n",
      "60000/60000 [==============================] - 202s 3ms/step - loss: 0.0356 - accuracy: 0.9890\n",
      "Epoch 7/10\n",
      "60000/60000 [==============================] - 204s 3ms/step - loss: 0.0330 - accuracy: 0.9895\n",
      "Epoch 8/10\n",
      "60000/60000 [==============================] - 202s 3ms/step - loss: 0.0304 - accuracy: 0.99091s - los\n",
      "Epoch 9/10\n",
      "60000/60000 [==============================] - 196s 3ms/step - loss: 0.0286 - accuracy: 0.9915\n",
      "Epoch 10/10\n",
      "60000/60000 [==============================] - 200s 3ms/step - loss: 0.0251 - accuracy: 0.9927\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "<keras.callbacks.callbacks.History at 0x1bca75c4520>"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "model.fit(trainer.x_train, trainer.y_train, batch_size=32, epochs=10)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 720x720 with 2 Axes>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "              precision    recall  f1-score   support\n",
      "\n",
      "           0       0.99      1.00      0.99       980\n",
      "           1       1.00      1.00      1.00      1135\n",
      "           2       1.00      1.00      1.00      1032\n",
      "           3       0.99      1.00      1.00      1010\n",
      "           4       1.00      0.99      0.99       982\n",
      "           5       1.00      0.99      0.99       892\n",
      "           6       1.00      0.99      0.99       958\n",
      "           7       0.99      0.99      0.99      1028\n",
      "           8       1.00      0.99      1.00       974\n",
      "           9       0.99      0.99      0.99      1009\n",
      "\n",
      "    accuracy                           0.99     10000\n",
      "   macro avg       0.99      0.99      0.99     10000\n",
      "weighted avg       0.99      0.99      0.99     10000\n",
      "\n"
     ]
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "from sklearn.metrics import plot_confusion_matrix\n",
    "from sklearn.metrics import classification_report\n",
    "import seaborn as sb\n",
    "\n",
    "def show_confusion_matrix(validations, predictions, num_classes):\n",
    "    matrix = metrics.confusion_matrix(validations, predictions)\n",
    "    plt.figure(figsize=(num_classes, num_classes))\n",
    "    hm = sb.heatmap(matrix,\n",
    "                cmap='coolwarm',\n",
    "                linecolor='white',\n",
    "                linewidths=1,\n",
    "                xticklabels=[0,1,2,3,4,5,6,7,8,9],\n",
    "                yticklabels=[0,1,2,3,4,5,6,7,8,9],\n",
    "                annot=True,\n",
    "                fmt='d')\n",
    "    plt.yticks(rotation = 0)\n",
    "    hm.invert_yaxis()\n",
    "    hm.set_ylim(0, len(matrix))\n",
    "    plt.title('Confusion Matrix')\n",
    "    plt.ylabel('True Label')\n",
    "    plt.xlabel('Predicted Label')\n",
    "    plt.show()\n",
    "\n",
    "x_test = model.predict(trainer.x_test)\n",
    "\n",
    "max_x_test = np.argmax(x_test, axis=1)\n",
    "max_y_test = np.argmax(trainer.y_test, axis=1)\n",
    "\n",
    "show_confusion_matrix(max_y_test, max_x_test, 10)\n",
    "\n",
    "print(classification_report(max_y_test, max_x_test))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Reading Lines from Pictures"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Image Reading\n",
    "ImageReadder class's  purpose is to open the given image and search for lines inside. It uses Canny and HoughLines method from OpenCV.\n",
    "- read_lines - reads the image and searches for lines.\n",
    "- show_lines - adds lines to lists (horizontal/vertical) and allows to show the image with lines found."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "import cv2\n",
    "import numpy as np\n",
    "\n",
    "class ImageReader:\n",
    "    def __init__(self, image):\n",
    "        self.lines = []\n",
    "        self.original_img = cv2.imread(image)\n",
    "        self.lines_img = cv2.imread(image)\n",
    "        self.horizontal = []\n",
    "        self.vertical = []\n",
    "        \n",
    "    def read_lines(self):\n",
    "        gray = cv2.cvtColor(self.original_img, cv2.COLOR_BGR2GRAY)\n",
    "        canny = cv2.Canny(gray, 50, 150, apertureSize = 3)\n",
    "        self.lines = cv2.HoughLines(canny, 1, np.pi/180, 200)\n",
    "            \n",
    "    def show_lines(self):\n",
    "        for line in self.lines:\n",
    "            rho,theta = line[0]\n",
    "            a = np.cos(theta)\n",
    "            b = np.sin(theta)\n",
    "            x0 = a*rho\n",
    "            y0 = b*rho\n",
    "            x1 = int(x0 + 1000*(-b))\n",
    "            y1 = int(y0 + 1000*(a))\n",
    "            x2 = int(x0 - 1000*(-b))\n",
    "            y2 = int(y0 - 1000*(a))\n",
    "            self.vertical.append([(x1, y1), (x2, y2)]) if theta == 0 else self.horizontal.append([(x1, y1), (x2, y2)])\n",
    "            cv2.line(self.lines_img, (x1,y1),(x2,y2),(0,0,255),2)\n",
    "        cv2.imshow('Lines read', self.lines_img)\n",
    "        cv2.waitKey(0)\n",
    "        cv2.destroyAllWindows()\n",
    "        "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "img_read = ImageReader('example.png')\n",
    "img_read.read_lines()\n",
    "img_read.show_lines()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Digits Predicting\n",
    "DigitPrediction is a class that reads each cell and predicts the cell's digit. It's goal is to return a correct sudoku. \n",
    "- update_sudoku - simple method which updates the saved sudoku.\n",
    "- get_reader_data - takes all important information from image reader (lines and image).\n",
    "- read_cell - checks every cell for number and adds the adjusted image with coordinates to lists.\n",
    "- digit_prediction - predicts the numbers according to previous readings\n",
    "- correctness_handler - separates predictions into high/low probability. The low probability will be replaced if user wishes to.\n",
    "- final_info - asks the user about reading. If it's incorrect, allows to change the number on given coordinate.\n",
    "- predict_digits - main method summarizing all class."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [],
   "source": [
    "class DigitPrediction:\n",
    "    def __init__(self, image_reader):\n",
    "        self.sudoku = np.zeros((81))\n",
    "        # readings\n",
    "        self.image_reader = image_reader\n",
    "        self.sudoku_images = []\n",
    "        self.rows = []\n",
    "        # predictions\n",
    "        self.prediction_probability = []\n",
    "        self.prediction_value = []\n",
    "        \n",
    "    def update_sudoku(self, values):\n",
    "        np.put(self.sudoku, [i[0]*9 + i[1] for i in self.rows], values)\n",
    "        self.sudoku = np.reshape(self.sudoku, (9,9))\n",
    "    \n",
    "    def get_reader_data(self):\n",
    "        print(\"\\nReading data from image_reader...\")\n",
    "        lines = self.image_reader.lines\n",
    "        horizontal = self.image_reader.horizontal\n",
    "        vertical = self.image_reader.vertical\n",
    "        image = self.image_reader.original_img\n",
    "        horizontal.sort()\n",
    "        vertical.sort()\n",
    "        print(\"Horizontal size: {0}, Vertical size: {1}.\".format(len(horizontal), len(vertical)))\n",
    "        return lines, horizontal, vertical, image\n",
    "    \n",
    "    def read_cell(self):\n",
    "        print(\"\\nReading cells images...\")\n",
    "        lines, horizontal, vertical, image = self.get_reader_data()\n",
    "        size_margin = int(image.shape[0]/100)\n",
    "        lines_margin = 1+len(vertical)%9\n",
    "\n",
    "        for i in range(0, len(vertical)-lines_margin):\n",
    "            for j in range(0, len(horizontal)-lines_margin):\n",
    "                if j % 2 == 0 and i % 2 == 0:\n",
    "                    x1 = horizontal[i][0][1] + size_margin\n",
    "                    y1 = vertical[j][0][0] + size_margin\n",
    "                    x2 = horizontal[i+lines_margin][0][1] - size_margin\n",
    "                    y2 = vertical[j+lines_margin][0][0] - size_margin\n",
    "                    crop_img = image[x1:x2, y1:y2]\n",
    "                    gray = cv2.cvtColor(crop_img, cv2.COLOR_BGR2GRAY)\n",
    "                    negative = cv2.bitwise_not(gray)\n",
    "                    if np.any(negative > 14):\n",
    "                        resized = cv2.resize(negative, (28,28), interpolation = cv2.INTER_AREA) \n",
    "                        reshaped = np.reshape(resized, (28,28,1))\n",
    "                        final = reshaped / 16\n",
    "                        self.sudoku_images.append(final)\n",
    "                        self.rows.append([int(i/2),int(j/2)])\n",
    "        print(\"Digits found: \", len(self.sudoku_images))\n",
    "                        \n",
    "    def digit_prediction(self, model):\n",
    "        print(\"\\nPredicting values...\")\n",
    "        self.prediction_probability = model.predict(np.asarray(self.sudoku_images))\n",
    "        self.prediction_value = model.predict_classes(np.asarray(self.sudoku_images))\n",
    "        print(\"Predicted values: \\n\", self.prediction_value)\n",
    "        \n",
    "    def correctness_handler(self):\n",
    "        print(\"\\nChecking the predictions probabilities...\")\n",
    "        high_probabilities = []\n",
    "        low_probabilities = []\n",
    "\n",
    "        for i in range(len(self.prediction_value)):\n",
    "            if self.prediction_probability[i][self.prediction_value[i]] > 0.7:\n",
    "                high_probabilities.append(self.prediction_value[i])\n",
    "            else:\n",
    "                high_probabilities.append(0)\n",
    "                low_probabilities.append(i)\n",
    "            if len(low_probabilities) > 9:\n",
    "                print(\"THE IMAGE WAS NOT READ CORRECTLY, TRY AGAIN!\")\n",
    "                raise\n",
    "        print(\"Nice! I got {} digits with over 70% probability.\".format(len(high_probabilities)))\n",
    "        print(\"I got {} digits with smol probability.\".format(len(low_probabilities)))\n",
    "        return high_probabilities, low_probabilities\n",
    "                \n",
    "    def final_info(self, high_probabilities, low_probabilities):\n",
    "        print(\"\\nThis is what I've read. Is it a correct sudoku?\\n Answer 'yes' if it's correct\\n\", self.sudoku)\n",
    "        answer = input()\n",
    "        if answer != \"yes\":\n",
    "            amount = 0 \n",
    "            while amount < len(low_probabilities):\n",
    "                print(\"Some cells were uncertain. Please tell me - what is the number in cell? {}\"\n",
    "                      .format(self.rows[low_probabilities[amount]]))\n",
    "                new_number = input()\n",
    "                high_probabilities[low_probabilities[amount]] = new_number\n",
    "                amount = amount + 1\n",
    "            print(\"Final version:\")\n",
    "            self.update_sudoku(high_probabilities)\n",
    "            print(self.sudoku)\n",
    "            \n",
    "    def predict_digits(self, model):\n",
    "        try:\n",
    "            self.read_cell()\n",
    "            self.digit_prediction(model)\n",
    "            high_probabilities, low_probabilities = self.correctness_handler()\n",
    "            self.update_sudoku(high_probabilities)\n",
    "            self.final_info(high_probabilities, low_probabilities)\n",
    "        except:\n",
    "            print(\"Unexpected error in DigitReader: \", sys.exc_info()[0])\n",
    "            raise"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Main\n",
    "Let's solve it!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "Reading cells images...\n",
      "\n",
      "Reading data from image_reader...\n",
      "Horizontal size: 18, Vertical size: 18.\n",
      "Digits found:  29\n",
      "\n",
      "Predicting values...\n",
      "Predicted values: \n",
      " [3 7 6 6 7 3 5 4 6 8 1 2 9 9 8 3 2 7 9 8 6 8 6 9 3 5 2 6 9]\n",
      "\n",
      "Checking the predictions probabilities...\n",
      "Nice! I got 29 digits with over 70% probability.\n",
      "I got 2 digits with smol probability.\n",
      "\n",
      "This is what I've read. Is it a correct sudoku?\n",
      " Answer 'yes' if it's correct\n",
      " [[0. 0. 0. 0. 0. 0. 0. 0. 0.]\n",
      " [0. 3. 0. 0. 0. 0. 0. 6. 0.]\n",
      " [0. 6. 7. 0. 3. 5. 0. 0. 4.]\n",
      " [6. 0. 8. 0. 2. 0. 9. 0. 0.]\n",
      " [0. 9. 0. 0. 8. 0. 0. 3. 0.]\n",
      " [0. 0. 2. 0. 7. 9. 8. 0. 6.]\n",
      " [8. 0. 0. 6. 9. 0. 3. 5. 0.]\n",
      " [0. 2. 6. 0. 0. 0. 0. 9. 0.]\n",
      " [0. 0. 0. 0. 0. 0. 0. 0. 0.]]\n",
      "no\n",
      "Some cells were uncertain. Please tell me - what is the number in cell? [1, 6]\n",
      "1\n",
      "Some cells were uncertain. Please tell me - what is the number in cell? [3, 3]\n",
      "1\n",
      "Final version:\n",
      "[[0. 0. 0. 0. 0. 0. 0. 0. 0.]\n",
      " [0. 3. 0. 0. 0. 0. 1. 6. 0.]\n",
      " [0. 6. 7. 0. 3. 5. 0. 0. 4.]\n",
      " [6. 0. 8. 1. 2. 0. 9. 0. 0.]\n",
      " [0. 9. 0. 0. 8. 0. 0. 3. 0.]\n",
      " [0. 0. 2. 0. 7. 9. 8. 0. 6.]\n",
      " [8. 0. 0. 6. 9. 0. 3. 5. 0.]\n",
      " [0. 2. 6. 0. 0. 0. 0. 9. 0.]\n",
      " [0. 0. 0. 0. 0. 0. 0. 0. 0.]]\n",
      "\n",
      "Solving the sudoku...\n",
      "\n",
      "\n",
      "\n",
      "4 8 9   2 6 1   5 7 3 \n",
      "2 3 5   8 4 7   1 6 9 \n",
      "1 6 7   9 3 5   2 8 4 \n",
      "\n",
      "\n",
      "6 7 8   1 2 3   9 4 5 \n",
      "5 9 1   4 8 6   7 3 2 \n",
      "3 4 2   5 7 9   8 1 6 \n",
      "\n",
      "\n",
      "8 1 4   6 9 2   3 5 7 \n",
      "7 2 6   3 5 8   4 9 1 \n",
      "9 5 3   7 1 4   6 2 8 \n"
     ]
    }
   ],
   "source": [
    "if __name__ == \"__main__\":\n",
    "    # Solver\n",
    "    sudoku_solver = Solver()\n",
    "    \n",
    "    digit_predictor = DigitPrediction(img_read)\n",
    "    digit_predictor.predict_digits(model)\n",
    "    \n",
    "    print(\"\\nSolving the sudoku...\\n\")\n",
    "    sudoku_solver.solve(digit_predictor.sudoku)\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "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.8.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}