Merge pull request #85 from ogamespec/11-deroute-user-manual

11 deroute user manual

docs/DerouteUserManual.md

@@ -0,0 +1,95 @@
+# Deroute manual
+
+## Overview
+
+The Deroute utility is designed for reverse engineering chips and motherboards.
+
+XXX: This manual only includes a section on machine learning for now. Basically everything else is self-descriptive and you can just poke the buttons to figure it out.
+The instructions will be expanded over time.
+
+## Machine Learning
+
+Neural networks are used to recognize elements of the chip or PCB being studied (vias, wires, standard cells).
+
+All the functionality to work with neural networks is done through a button with the brain.
+
+![machine_learning_tools.png](imgstore/machine_learning_tools.png)
+
+### Create ML model
+
+This dialog is used to create a ML model (neural network).
+
+![create_ML_model.png](imgstore/create_ML_model.png)
+
+The model includes neural network hyperparameters (such as `learningRate`), as well as a list of features, which are essentially neural network outputs.
+
+A small chunk of the main image (16x16) is fed to the input of the neural network, and the neural network outputs the result (makes a classification).
+
+In place of the found feature an entity is put, which is specified in the `Entities` column.
+
+The list of a feature's properties:
+- Name: the name of the feature to display and teach
+- Description: just a description for clarity
+- Image: just a picture for clarity. You may select any icon for purely informational purposes. A click on it will bring up an icon selection dialog box.
+- Entites: Entities which should be added in the place of a recognized feature. Clicking on a cell opens a MiniEntityBox, where you need to draw entities
+
+Suggestions for the number of features:
+- You need at least 2 features, so that neural network could make a correct classification.
+- It is desirable to choose as many different features as possible. Here you have to use your intuition - if a human being distinguishes one feature from another (for example a vias from a wire), you can expect the same thing from a neural network.
+
+### Load and save ML model
+
+Self-descriptive operations.
+
+The ML model is saved in an XML file.
+
+### View the currently loaded ML model
+
+To see the current ML model, click on `Neural model` in the status bar:
+
+![show_ML_model.png](imgstore/show_ML_model.png)
+
+#### Model training
+
+The most fun part.
+
+To train the model, you must first load the source image (File -> Load Image).
+
+The train dialog looks like this:
+
+![train_ML_model.png](imgstore/train_ML_model.png)
+
+- Neighbour field: area of the original image from which a small piece, 16x16 pixels, will be taken. You can move the green square with the mouse.
+- Feature: the piece which you want to teach the neural network to
+- Guess: with this button you can check what the neural network is thinking on the selected feature. This is how you may check if the network is trained. Above the Guess button you will see a description of the feature (the icon you chose when you created the model (Image), the description (Description), and the name of the feature (Name)). If the neural network doesn't know what kind of feature it is, it will tell you so.
+- List of Features: in this list you must select the feature you want your neural network to train.
+- Next: skip teaching and select next feature. You may do it when there is some garbage on the image or you want to train the neural network in another part of it.
+- Train: the neural network is trained with the selected feature from the list
+
+Recommendations for training:
+- You should not train a network with one feature in a row. Such training will overtrain and unbalance it. You should try to change fields and teach them different features as often as possible.
+- Practice has shown that to train a network for simple recognition (wires, vias) it is enough to teach it about 100-200 times.
+
+### Run the model
+
+To start recognition process, you must first load the source image (File -> Load Image).
+
+After launching, the modeless dialog box with the recognition progress is displayed:
+
+![ML_Running.png](imgstore/ML_Running.png)
+
+The recognition of the original image is done in a zigzag pattern, with a step of 1 pixel.
+
+The recognition process can be stopped at any time by closing the `Run Model` dialog.
+
+The result of the recognition is something like the following:
+
+![ML_results.jpg](imgstore/ML_results.jpg)
+
+XXX: Currently the entities found are overlapping on top of each other, this will be fixed in the next release.
+
+XXX: The dialog currently does not write readiness percentage and does not close automatically, this will be fixed in the next release.
+
+The above flaws do not prevent you from training the model, so your trained model can still be used later, after the above flaws are fixed.
+
+Translated with DeepL.com

docs/DerouteUserManualRus.md

@@ -0,0 +1,95 @@
+# Руководство по Deroute
+
+## Обзор
+
+Утилита Deroute предназначена для реверс инжиниринга микросхем и материнских плат.
+
+XXX: Данная инструкция пока включает только раздел по машинному обучению. В принципе всё остальное самоописательное и можно просто потыкать кнопочки, чтобы разобраться.
+Инструкция будет расширена со временем.
+
+## Машинное обучение
+
+Нейросети применяются для распознавания элементов изучаемой микросхемы или PCB (виасы, провода, стандартные ячейки).
+
+Весь функционал для работы с нейросетями производится через кнопку с мозгом.
+
+![machine_learning_tools.png](imgstore/machine_learning_tools.png)
+
+### Создать ML модель
+
+Данный диалог используется для создания ML модели (нейросети).
+
+![create_ML_model.png](imgstore/create_ML_model.png)
+
+Модель включает в себя гиперпараметры нейросети (такие как `learningRate`), а также список фич, которые по сути являются выходами нейросети.
+
+На вход нейросети подается небольшой кусочек основного изображения (16x16), а нейросеть на выходе выдает результат (производит классификацию).
+
+На место найденной фичи ставится сущность, которая указана в столбце `Entities`.
+
+Список свойств фичи:
+- Name: имя фичи для отображения и обучения
+- Description: просто описание для наглядности
+- Image: просто картинка для наглядности. Можно выбрать любую иконку чисто в информативных целях. При нажатии открывается диалог выбора иконки
+- Entites: сущности, которые необходимо добавить на место распознанной фичи. При нажатии на ячейку открывается MiniEntityBox, где нужно нарисовать сущности
+
+Рекомендации по количеству фич:
+- Нужно хотя бы 2 фичи, чтобы нейросеть могла делать корректную классификацию
+- Фичи желательно выбирать максимально разными. Тут нужно воспользоваться своей интуицией - если человек однозначно отличает одну фичу от другой (например виас от провода), то этого
+можно ожидать и от нейросети.
+
+### Загрузить и сохранить ML модель
+
+Самоописательные операции.
+
+ML модель сохраняется в XML файл.
+
+### Посмотреть текущую загруженную ML модель
+
+Для того чтобы посмотреть текущую ML модель нужно нажать в строке состояние на пункт `Neural model`:
+
+![show_ML_model.png](imgstore/show_ML_model.png)
+
+### Обучение модели
+
+Самая веселая часть.
+
+Для обучения модели необходимо предварительно загрузить исходное изображение (File -> Load Image).
+
+Диалог обучения выглядит следующим образом:
+
+![train_ML_model.png](imgstore/train_ML_model.png)
+
+- Neighbour field: участок исходного изображения откуда будет браться небольшой кусочек, 16x16 пикселей. Мышкой можно двигать зеленый квадратик.
+- Feature: отображается кусочек которому нужно обучить нейросеть
+- Guess: этой кнопкой можно проверить что думает нейросеть по выбранной фиче. Так можно проверять обученность нейросети. Над кнопкой Guess появится описание фичи (иконка, которую вы выбрали при создании модели (Image), описание (Description) и имя фичи (Name)).
+Если нейросеть не знает что это за фича, она так и скажет.
+- Список фич: в этом списке нужно выбрать фичу для обучения нейросети
+- Next: пропустить обучение и выбрать следующую фичу. Это можно делать когда на изображении какой-то мусор или хочется обучить нейросеть на другом участке изображения
+- Train: нейросеть обучается указанной из списка фичи
+
+Рекомендации по обучению:
+- Не следует задрачивать нейросеть одной фичей подряд. Такое обучение переобучит и разбалансирует нейросеть. Нужно стараться как можно чаще менять field и обучать нейросеть разным фичам.
+- Практика показала, что натаскать сеть на простое распознавание (провода, виасы) достаточно обучить её примерно 100-200 раз.
+
+### Запуск модели
+
+Для запуска модели необходимо предварительно загрузить исходное изображение (File -> Load Image).
+
+После запуска отображается modeless диалог с прогрессом сканирования:
+
+![ML_Running.png](imgstore/ML_Running.png)
+
+Распознавание исходного изображения производится зигзагом, с шагом 1 пиксель.
+
+Процесс распознавания можно в любой момент остановить, закрыв диалог `Run Model`.
+
+В результате распознавания получается примерно следующее:
+
+![ML_results.jpg](imgstore/ML_results.jpg)
+
+XXX: В настоящее время найденные сущности "наслаиваются" друг на друга, это будет исправлено в следующем релизе.
+
+XXX: В настоящее время диалог не пишет процент готовности и не закрывается автоматически, это будет исправлено в следующем релизе.
+
+Указанные недостатки не препятствуют обучению модели, поэтому ваша обученная модель может быть использована и потом, после устранения вышеуказанных недостатков.