Completed the Bulgarian translation of the docs

boytchev · Aug 14, 2024 · 8bae015 · 8bae015
1 parent 2085867
commit 8bae015
Show file tree

Hide file tree

Showing 2 changed files with 213 additions and 54 deletions.
diff --git a/docs/userguide-bg.md b/docs/userguide-bg.md
@@ -5,51 +5,48 @@
 
 ## <small><small>This document is also available in [English](userguide.md)</small></small>
 
-
-- **[Инициализация](#инициализация)** (<small>[Минимална програма](#минимална-програма) | [Инсталация](#инсталация) | [Видове фигури](#видове-фигури) | [АПИ](#апи)</small>)
 - **[Части на тялото](#части-на-тялото)** (<small>[Централни части на тяло](#централни-части-на-тяло) | [Горни крайници](#горни-крайници) | [Долни крайници](#долни-крайници)</small>)
 - **[Поза на тялото](#поза-на-тялото)** (<small>[Статична поза](#статична-поза) | [Динамична поза](#динамична-поза) | [Работа с пози](#работа-с-пози)</small>)
-- **[Други функционалности](#други-функционалности)** (<small>[Собствени цветове](#собствени-цветове) | [Скриване на части от тялото](#скриване-на-части-от-тялото) | [Собствени части на тяло](#собствени-части-на-тяло) | [Глобална позиция](#глобална-позиция)</small>)
-
-
-
-# Инициализация
-
-Библиотеката **mannequin.js** се предоставя като комплект от JavaScript модули.
-
-
-
-### Инсталация
-
-TODO
-
+- **[Други функционалности](#други-функционалности)** (<small>[Собствени цветове](#собствени-цветове) | [Модификация на тяло](#модификация-на-тяло) | [Позициониране](#глобална-позиция)</small>)
+- **[Използване на Mannequin.js](#използване-на-mannequinjs)** (<small>[CDN](#пускане-от-cdn) | [локален уеб сървър](#пускане-през-локален-уеб-сървър) | [Nodes.js](#пускане-през-nodesjs) | [АПИ](#апи)</small>)
 
 
-### Минимална програма
+Mannequin.js е несложна библиптека за движение на фигури. Формата и движенията
+им става през JavaScript. Ето кратък пример, който показва мъжка фигура
+[пример на живо](example-minimal-cdn.html).
 
-Това е относително минимална програма, която създава мъжка фигура в браузър ([пример на живо](example-minimal.html)):
-
-``` xml
+```html
 <!DOCTYPE html>
+
 <html>
-    <head>
-        <script src="../src/importmap.js"></script>
-    </head>
-    <body>
-        <script type="module">
-            import { createStage, Male } from "mannequin";
-            createStage( );
-            new Male();
-        </script>
-    </body>
+
+<head>
+   <script type="importmap">
+   {
+      "imports": {
+         "three": "https://cdn.jsdelivr.net/npm/[email protected]/build/three.module.js",
+         "three/addons/": "https://cdn.jsdelivr.net/npm/[email protected]/examples/jsm/",
+         "mannequin": "https://cdn.jsdelivr.net/npm/mannequin-js@latest/src/mannequin.js"
+      }
+   }
+   </script>
+</head>
+
+<body>
+   <script type="module">
+      import { createStage, Male } from "mannequin";
+      createStage( );
+      new Male();
+   </script>
+</body>
 </html>
 ```
 
-Помощната функция `createStage()` създава сцената, осветлението, камерата,
-земята и т.н. `Male` конструира мъжка фигура.
 
 
 
+# Части на тялото
+
 ### Видове фигури
 
 Фигурите в библиотеката се създават като инстанции на класовете `Male(height)`,
@@ -84,19 +81,6 @@ var kid = new Child();
 `Male` и `Female` придават мъжествена и женствена поза.
 
 
-### АПИ
-
-Библиотеката mannequin.js дефинира следните фукции и класове:
-
-* `getVersion()` &ndash; функция, текущата версия на mannequin.js като число; напр. 5.2
-* `getPostureVersion()` &ndash; функция, текущата версия на формата на данните, описващи поза
-* `getGroundLevel()` &ndash; функция, вертикалното положение на земята в метри
-* `blend(p,q,k)` &ndash; функция, смесена поза на пози *p* и *q* с коефициент *k*
-* `createStage(animationLoop)` &ndash; функция, създава сцена със земя и светлини
-* `getStage()` &ndash; функция, текущата сцене
-
-
-# Части на тялото
 
 Всички видове фигури имат една и съща структура. Например, дясната ръка
 в кръстена `r_arm`. За някои части на тялото mannequin.js използва името
@@ -489,7 +473,7 @@ man.l_nails.recolor( 'black' );
 
 
 
-### Скриване на части от тялото
+### Модификация на тяло
 
 Всяка част от тялото може да бъде скрита. Това не
 премахва нея и нейния графичен образ от фигурата, а
@@ -515,9 +499,6 @@ man.l_arm.hide();
 man.r_arm.hide();
 ```
 
-
-### Собствени части на тяло
-
 Частите на тялото са наследници на класа [`THREE.Object3D`](https://threejs.org/docs/#api/en/core/Object3D) и поддържат
 неговите свойства и методи. Въпреки това, поради конструкцията
 на скелета и свързването на ставите, мащабирането на част от
@@ -643,6 +624,184 @@ man.position.y += (GROUND_LEVEL-bottom);
 ``` javascript
 man.stepOnTheGround();
 ```	
+
+
+
+# Използване на mannequin.js
+
+Библиотеката mannequin.js се предоставя като комплект от JavaScript модули.
+Предназначена е да се използва от CDN. Най-вероятно библиотеката може да бъде
+инсталирана с `npm`, но това не е пробвано все още.
+
+Библиотеката използва Three.js и очаква следните importmaps да бъдат дефинирани:
+
+* `three`: указател към Three.js файла `three.module.js` 
+* `three/addons/`: указател към пътя на добавките на Three.js
+* `mannequin`: указател към главния файл на библиотеката `mannequin.js`
+
+Следващите подсекции демонстраират някои от конфигурационните сценарии на
+използване на mannequin.js.
+
+
+### Пускане от CDN
+
+Съкращението CDN означава [Content Delivery Network (Мрежа за доставка на съдържание)](https://bg.wikipedia.org/wiki/Мрежа_за_доставка_на_съдържание).
+
+Относно mannequin.js CDN служи като хостинг на библиотечните файлове. Към
+момента на изготвяне на този докумен се препоръчва ползването на [jsDelivr](https://cdn.jsdelivr.net).
+Други CDN също са възможни.
+
+Основните предимства на използването на CDN са:
+* няма нужда от инсталиране на mannequin.js
+* няма нужда от инсталиране на nodes.js или друг мениджър на JS модули
+* няма нужда от инсталиране на локален уеб сървър
+* потребителски файл може да се стартира директно в браузър
+
+Основните недостатъци на използването на CDN са:
+* изисква се интернет достъпът до CDN при стартиране на програмата
+* указателите към Three.js и mannequin.js трябва да бъдат дефинирани като importmaps
+
+Донякъде минимална програма, която използва mannequin.js от този CDN, е показана
+в този [пример на живо](example-minimal-cdn.html). Ако файлът е свален локално, той
+може да се стартира директно без допълнителна инсталация. Указателите в importmaps в
+примера сочат към конкретна версия на Three.js и към най-новата версия на mannequin.js.
+
+
+```html
+<!DOCTYPE html>
+
+<html>
+
+<head>
+   <script type="importmap">
+   {
+      "imports": {
+         "three": "https://cdn.jsdelivr.net/npm/[email protected]/build/three.module.js",
+         "three/addons/": "https://cdn.jsdelivr.net/npm/[email protected]/examples/jsm/",
+         "mannequin": "https://cdn.jsdelivr.net/npm/mannequin-js@latest/src/mannequin.js"
+      }
+   }
+   </script>
+</head>
+
+<body>
+   <script type="module">
+      import { createStage, Male } from "mannequin";
+      createStage( );
+      new Male();
+   </script>
+</body>
+</html>
+```
+
+Много от примерите в този документ използват скрипта `importmap.js`
+за генериране на importmaps  и инжектирането им в страницата. Това се прави единствено
+за поддържане на по-кратък код и за лесно превключване към други версии както на
+Three.js, така и на mannequin.js.
+
+
+
+### Пускане през локален уеб сървър
+
+По същество пускането е същото като от CDN, като вместо CDN се ползва локална папка.
+Единствената промяната са пътищата в importmaps, които сочат към локалните
+файлове и папки.
+
+Основните предимства на използването на локални файлове са:
+
+* не е необходим достъп до интернет
+* няма нужда от инсталиране на nodes.js или друг мениджър на JS модули
+* защитеност от евентуална несъвместима промяна в онлайн библиотеките
+* потребителски файл може да се стартира директно в браузър
+* потребителски код може да използва модули и може да бъде разделен на няколко файла
+
+Основните недостатъци на използването на локални файлове са:
+
+* mannequin.js и всички негови изходни файлове трябва да бъдат свалени
+* трябва да бъде инсталиран локален уеб сървър
+* указателите към локалните Three.js и mannequin.js все пак трябва да са дефинирани в importmaps
+
+Възможно е едновременното използване на CDN и на локални файлове. Например,
+използва се онлайн Three.js от CDN и локалнен mannequin.js. Това се определя от
+пътищата в importmaps.
+
+### Пускане през nodes.js
+
+Библиотеката mannequin.js се предоставя като NPM пакет. Ако nodes.js е инсталиран
+на потребителското устройство, трябва да е възможно да се инсталира mannequin.js
+и да се използва директно.
+
+Основните предимства на използването на nodes.js:
+
+* не е необходим достъп до интернет, освен за самата инсталация на пакета
+* няма нужда да се ползват importmaps (целият таг за importmaps се спестява)
+* защитеност от евентуална несъвместима промяна в онлайн библиотеките
+
+Основните недостатъци на използването на nodes.js:
+* nodes.js трябва да бъде инсталиран
+* mannequin.js трябва да бъде инсталиран
+
+Забележка: Този подход не е тестван. Ако установите, че не работи, но знаете
+какво трябва да се коригира, за да проработи, моля, свържете се с нас.
+
+
+### АПИ
+
+Библиотеката mannequin.js дефинира следните фукции и класове:
+
+* `createStage(animationLoop)` &ndash; функция, създава сцена със земя и светлини
+* `getStage()` &ndash; функция, текущата сцена*
+* `getVersion()` &ndash; функция, текущата версия на mannequin.js като число; напр. 5.2
+* `getPostureVersion()` &ndash; функция, текущата версия на формата на данните, описващи поза
+* `getGroundLevel()` &ndash; функция, вертикалното положение на земята в метри
+* `blend(p,q,k)` &ndash; функция, смесена поза на пози *p* и *q* с коефициент *k*
+* `Mannequin(feminine,height)` &ndash; клас, най-обща фигура
+* `Male(height)` &ndash; клас, мъжка фигура
+* `Female(height)` &ndash; клас, женска фигура
+* `Child(height)` &ndash; клас, детска фигура
+
+Всички фигури (инстанции на `Mannequin`, `Male`, `Female` и `Child`) имат еднакъв
+набор от свойства и методи.
+
+* `body`, `pelvis`, `torso`, `neck`, `head` &ndash; свойства, основни части на тяло
+* `l_leg`, `l_knee`, `l_ankle` &ndash; свойства, части на ляв крак
+* `r_leg`, `r_knee`, `r_ankle` &ndash; свойства, части на десен крак
+* `l_arm`, `l_elbow`, `l_wrist`, `l_finger_0`...`l_finger_4`, `l_fingers`, `l_nails` &ndash; свойства, части на лява ръка
+* `r_arm`, `r_elbow`, `r_wrist`, `r_finger_0`...`r_finger_4`, `r_fingers`, `r_nails` &ndash; свойства, части на дясна ръка
+* `feminine` &ndash; свойство, булев флаг дали фигура е женска
+* `bend`, `tilt`, `turn` &ndash; свойства, завъртяност на тяло
+* `posture`, `postureString` &ndash; свойства, поза на фигура
+* `stepOnGround()` &ndash; метод, премества вертикално фигура, за да докосне земята
+* `recolor(...)` &ndash; метод, променя цветовете на частите на тяло
+
+Всички части на тяло имат подобни свойства и методи. Някои от свойствата за завъртане
+не са налични за всички части поради биологически причини.
+
+* `posture` &ndash; свойство, поза на част на тяло (масив от ъглите на завъртане)
+* `hide()`, `show()` &ndash; методи, скриване и показване на част от тяло
+* `attach(image)`, `detach(image)` &ndash; методи, добавяне и премахване на потребителски 3D обект ктм част на тяло
+* `point(x,y,z)` &ndash; метод, изчисляване на глобални координати на локална позиция (x,y,z) спрямо част на тяло
+* `recolor(...)` &ndash; метод, смяна на цветовете на част на тяло
+* `label(...)` &ndash; метод, добавяне на 3D текст към част на тяло
+* `bend`, `tilt`, `turn` &ndash; свойства, завъртяност на глезени, тяло, торс и китки
+* `bend` &ndash; свойство, завъртяност на лакти и колена
+* `bend`, `straddle`, `turn` &ndash; свойства, завъртяност на пръсти
+* `raise`, `straddle`, `turn` &ndash; свойства, завъртяност на ръце и крака
+* `nod`, `tilt`, `turn` &ndash; свойства, завъртяност на глава
+
+Пръстите имат допълителни свойства и методи за достъп до тяхната структура:
+
+* `mid` &ndash; свойство, средна фаланга на пръст
+* `mid.bend` &ndash; метод, завъртяност на средната фаланга
+* `tip` &ndash; свойство, крайна фаланга на пръст
+* `tip.nail` &ndash; свойство, нокът на пръст
+* `tip.bend` &ndash; метод, завъртяност на крайната фаланга
+* `tip.nail.bend` &ndash; метод, завъртяност на нокът ... шегувам се, няма такъв метод
+
+Груповите свойства `l_fingers` и `r_fingers` съдържат:
+* `finger_0`...`finger_4` &ndash; свойства, отделните пръсти, съответстващи на `l_finger_0`...`l_finger_4` и `r_finger_0`...`r_finger_4`
+* `bend` &ndash; метод, свиване на всички пръсти, включително средните и крайните фаланги
+