diff --git a/docs/examples.ru.md b/docs/examples.ru.md index 4ae71f5..cd5650b 100644 --- a/docs/examples.ru.md +++ b/docs/examples.ru.md @@ -1,10 +1,15 @@ # Примеры DrawZero -На этой странице собрана галерея примеров, демонстрирующих возможности библиотеки DrawZero. +На этой странице собрана галерея из 21 примера, которые поставляются вместе с библиотекой +DrawZero. Каждый блок ниже подтягивает код напрямую из каталога +`src/drawzero/examples`, поэтому вы видите ровно те же исходники, что и при установке +пакета. Используйте галерею как справочник: переходите от иллюстраций к коду, сверяйтесь +с комментариями в исходниках и экспериментируйте у себя в редакторе. ## Начало работы -Эти примеры показывают самые основы вывода изображения на экран. +Эти примеры показывают, как вывести первые примитивы на экран и разобраться с базовым +циклом `run()`. ### 00_hello_world.py @@ -22,7 +27,8 @@ ## Использование циклов и цветов -Узнайте, как использовать циклы для создания более сложных узоров и как работать с разными цветами. +Используйте циклы и случайные значения, чтобы быстро получать выразительные узоры и +научиться передавать цвета в именованном и RGB-форматах. ### 02_loops_and_rgb_colors.py @@ -47,7 +53,8 @@ ## Точки и черепашья графика -Класс `Pt` позволяет использовать векторную математику и команды рисования в стиле "черепашки". +Класс `Pt` из публичного API работает и как вектор, и как "черепаха". Эти примеры показывают +арифметику точек и построение фигур через повороты и смещения. ### 05_points.py @@ -65,7 +72,8 @@ ## Анимация -Оживите свои рисунки с помощью анимации. +Здесь начинается анимация: цикл `while True`, `tick()`, `clear()` и дополнительные эффекты, +которые встречаются в примерах `07`–`10`. ### 07_animation_circles.py @@ -97,7 +105,8 @@ ## Продвинутое рисование -Изучите более продвинутые возможности, такие как прозрачность, рендеринг изображений и цветовые градиенты. +Эти скрипты раскрывают дополнительные функции библиотеки: прозрачность, загрузку изображений +и градиенты, на которых основаны многие визуальные эффекты из исходников. ### 11_transparency_and_line_width.py @@ -122,7 +131,7 @@ ## Интерактивные примеры -Сделайте свои творения интерактивными, реагируя на ввод с клавиатуры и мыши. +Добавьте управление с клавиатуры и мыши, чтобы рисунки реагировали на пользователя в реальном времени. ### 14_animation_close_vertex.py @@ -154,7 +163,7 @@ ## Игры -Создавайте простые игры с помощью библиотеки DrawZero. +И, наконец, несколько мини-игр, собранных из примитивов, анимации и обработки ввода. ### 18_game_stars.py diff --git a/docs/examples_overview.ru.md b/docs/examples_overview.ru.md index b218939..72b96f7 100644 --- a/docs/examples_overview.ru.md +++ b/docs/examples_overview.ru.md @@ -1,30 +1,37 @@ # Обзор примеров -Пакет `src/drawzero/examples` содержит запускаемые скрипты, которые служат одновременно дымовыми тестами и демонстрацией использования. В таблице ниже показано назначение каждого скрипта, чтобы вы могли выбрать подходящую отправную точку при поиске неисправностей или расширении функциональности. +Каталог `src/drawzero/examples` содержит 21 сценарий, которые авторы библиотеки +используют как регрессионные тесты и обучающие демо. Они демонстрируют реальные +приёмы из исходного кода и дополняют разделы документации. В таблице ниже указано, +какую тему поднимает каждый файл и за какими функциями стоит следить, когда вы +изучаете пример или ищете отправную точку для своей задачи. -| Файл | Фокус | Ключевые идеи | +| Файл | О чём пример | На что обратить внимание | | --- | --- | --- | -| `00_hello_world.py` | Первый рендеринг на холсте | Рисует холст с рамкой, разделяет текст на два языка и запускает цикл `run()`. | -| `01_grid_and_coordinates.py` | Обзор системы координат | Рендерит вспомогательную сетку `grid()`, затем аннотирует различные примитивы в известных координатах. | -| `02_loops_and_rgb_colors.py` | Искусство, управляемое циклом | Использует цикл `for` и случайные кортежи RGB для рисования вертикальных полос различной высоты. | -| `03_simple_objects.py` | Каталог примитивов | Демонстрирует каждый примитив рисования (линии, круги, повернутые прямоугольники, многоугольники, выравнивание текста). | -| `04_loops_sin_plot.py` | Построение математических графиков | Строит синусоиду, сшивая короткие отрезки линий вдоль оси X. | -| `05_points.py` | Помощник [`Pt`](pt.md) как вектор/черепаха | Показывает, как класс `Pt` поддерживает арифметику, движение и вращение в стиле черепахи в циклах. | -| `06_turtle_style.py` | Рисование многоугольников с помощью [`Pt`](pt.md) | Вращает экземпляр `Pt` для построения правильных многоугольников для сторон от 3 до 10 с использованием операций черепахи. | -| `07_animation_circles.py` | Минимальный цикл анимации | Изменяет положение, радиус и цвет круга с течением времени, вызывая `tick()` на каждом кадре. | -| `08_animation_traffic_light.py` | Анимация на основе состояний | Повторно использует помощника для рисования светофора и использует `sleep()` для переключения цветов. | -| `09_animation_rectangles.py` | Сложная анимация | Сочетает математику `Pt` с логикой вращения/орбиты, прозрачностью и условными эффектами. | -| `10_animation_planets.py` | Орбитальное движение | Вычисляет круговое движение для пары планета/луна и перерисовывает каждый кадр. | -| `11_transparency_and_line_width.py` | Альфа-смешивание и толщина обводки | Демонстрирует различные значения альфа-канала и толщины линий на кругах, прямоугольниках, многоугольниках и эллипсах. | -| `12_images.py` | Рендеринг изображений | Загружает `cat.png` из папки примеров, демонстрирует масштабирование и альфа-канал при выводе изображений. | -| `13_gradients.py` | Помощник [Gradient](gradient.md) | Создает несколько шкал `Gradient` и визуализирует их с помощью сложенных прямоугольников. | -| `14_animation_close_vertex.py` | Анимация графа близости | Перемещает случайные узлы `Pt` с циклическим движением, рисует линии между соседними парами и использует оверлей FPS. | -| `15_animation_firework.py` | Система частиц | Реализует классы `Particle` и `Firework` с обновлениями физики, свечением на основе градиента и логикой очистки. | -| `16_keyboard_and_mouse.py` | Обработка ввода | Читает массивы состояний клавиш и очереди событий для перемещения квадрата, отслеживания вводимых символов и следования за мышью. | -| `17_mouse_tube.py` | Эффект следа мыши | Захватывает `mouse_pos()` на каждом кадре, выращивает концентрические круги с градиентом по мере их старения. | -| `18_game_stars.py` | Мини-игра 3D-звездное поле | Использует датаклассы, случайные звезды и управление WASD/QE для навигации по псевдо-3D полю. | -| `19_game_colors.py` | Игра на реакцию | Отображает слова-цвета в сравнении с фактическими цветами, обрабатывает выбор кнопок мыши со штрафами по времени. | -| `20_game_racing.py` | Многопользовательская мини-игра | Назначает отдельные привязки клавиш для каждой машины, прокручивает предварительно вычисленную дорогу и ведет счет для каждого игрока. | -| `99_errors.py` | Демонстрация сообщений об ошибках | Принудительно вызывает ошибки проверки в режиме `EJUDGE_MODE`, чтобы продемонстрировать локализованную диагностику, выдаваемую конвертерами. | +| `00_hello_world.py` | Первый вывод на холст | Последовательность `from drawzero import *`, вызов `run()` и базовая рамка окна. | +| `01_grid_and_coordinates.py` | Система координат | Вспомогательная сетка `grid()`, подписи текста и расположение фигур по известным точкам. | +| `02_loops_and_rgb_colors.py` | Генеративное искусство | Цикл `for`, случайные RGB‑кортежи и построение полос разной высоты. | +| `03_simple_objects.py` | Каталог примитивов | Все основные функции рисования: линии, окружности, многоугольники, эллипсы и выравнивание текста. | +| `04_loops_sin_plot.py` | Графики функций | Построение синусоиды из коротких отрезков с шагом по оси X. | +| `05_points.py` | Векторный помощник [`Pt`](pt.md) | Арифметика, нормализация и черепашьи операции `Pt` в циклах. | +| `06_turtle_style.py` | Черепашьи многоугольники | Повороты `Pt`, конструирование правильных многоугольников и заливка. | +| `07_animation_circles.py` | Минимальная анимация | Связка `tick()`, `clear()` и параметров окружности, которые меняются каждый кадр. | +| `08_animation_traffic_light.py` | Машина состояний | Комбинация функций рисования с `sleep()` для плавного переключения цветов. | +| `09_animation_rectangles.py` | Сложные траектории | Использование `Pt`, прозрачности и условных эффектов для движения нескольких объектов. | +| `10_animation_planets.py` | Орбитальная система | Расчёт кругового движения планеты и спутника с перерисовкой на каждом кадре. | +| `11_transparency_and_line_width.py` | Прозрачность и обводка | Сравнение значений `alpha` и `line_width` на разных примитивах. | +| `12_images.py` | Работа с изображениями | Загрузка `cat.png`, масштабирование и использование альфа‑канала при выводе. | +| `13_gradients.py` | Помощник [Gradient](gradient.md) | Создание палитр и их визуализация в виде составных прямоугольников. | +| `14_animation_close_vertex.py` | Ближайшие соседи | Случайные вершины `Pt`, линии между ближайшими парами и счётчик FPS. | +| `15_animation_firework.py` | Система частиц | Классы `Particle`/`Firework`, обновление физики и постэффекты на градиентах. | +| `16_keyboard_and_mouse.py` | Обработка ввода | Глобальные очереди клавиатуры и мыши, слежение за курсором и ввод текста. | +| `17_mouse_tube.py` | Светящийся след мыши | `mouse_pos()` на каждом кадре, нарастающие круги и плавное затухание. | +| `18_game_stars.py` | Псевдо‑3D полёт | Датаклассы, управление WASD/QE и перемещение звёзд с перспективой. | +| `19_game_colors.py` | Игра на реакцию | Сравнение цвета текста и фона, обработка кликов и штраф по таймеру. | +| `20_game_racing.py` | Гоночный экран на двоих | Индивидуальные привязки клавиш, прокрутка трека и отдельный счёт для игроков. | +| `99_errors.py` | Сообщения об ошибках | Примеры исключений и логирование диагностики в режиме `EJUDGE_MODE`. | -При добавлении новых примеров следите за тем, чтобы их можно было безопасно импортировать (тесты импортируют модули напрямую), и предпочитайте конечные циклы или защищайте бесконечные циклы блоком `if __name__ == "__main__"`. +Все эти файлы можно безопасно импортировать: тесты проекта делают именно так, чтобы +убедиться в корректности API. Если вы добавляете собственный пример, оставляйте +бесконечные циклы только внутри блока `if __name__ == "__main__":` или заменяйте их +конечными циклами, чтобы импорт не зависал. diff --git a/docs/index.ru.md b/docs/index.ru.md index 4c205f5..86a6ead 100644 --- a/docs/index.ru.md +++ b/docs/index.ru.md @@ -1,16 +1,18 @@ # DrawZero -DrawZero помогает рисовать на виртуальном холсте почти без предварительной настройки. В -документации ниже собраны самые полезные разделы, чтобы вы могли сразу перейти к -нужной теме. +DrawZero помогает рисовать на виртуальном холсте почти без предварительной настройки. +Ниже собраны разделы, которые чаще всего нужны на старте. Каждый из них основан на +оригинальных исходниках библиотеки и пересекается с галереей из 21 учебного примера, +которую авторы поставляют вместе с пакетом. ## Быстрая навигация - [Установка](installation.md) – установите библиотеку и запустите свой первый скрипт. -- [Графические примитивы](primitives.md) – изучите все основные фигуры, цвета и - функции для работы с текстом. -- [Анимация](animation.md) – разберитесь с игровым циклом, функцией `tick()` и следами - движения для создания анимированных скетчей. -- [Обзор примеров](examples_overview.md) – просмотрите запускаемые демо-скрипты, - которые объединяют примитивы и функции для анимации. +- [Графические примитивы](primitives.md) – разберите ключевые фигуры, именованные и + RGB‑цвета, текст и вспомогательные функции, которые лежат в основе почти каждого + примера из пакета `src/drawzero/examples`. +- [Анимация](animation.md) – разберитесь с игровым циклом, функцией `tick()` и приёмами + создания следов, которые используются в динамических примерах (см. скрипты `07`–`17`). +- [Обзор примеров](examples_overview.md) – просмотрите все 21 сценарий от авторов, + чтобы быстрее сопоставлять документацию с реальным кодом.