Major refactoring and unification of color handling

boytchev · Aug 8, 2024 · 1943920 · 1943920
1 parent 15109dd
commit 1943920
Show file tree

Hide file tree

Showing 22 changed files with 260 additions and 158 deletions.
diff --git a/docs/example-custom-colors.html b/docs/example-custom-colors.html
@@ -9,15 +9,12 @@
 <body>
 	<script type="module">
 
-	import { createScene, Male, setColors } from 'mannequin';
+	import { createScene, Male } from 'mannequin';
 
 	createScene( animate );
 
-	// gobal colours
-	setColors( 'lightgreen', 'black', 'black', 'white', 'darkolivegreen', 'darkslategray', 'yellow' );
-
 	var man = new Male();
-
+	
 	man.torso.bend = 30;
 
 	man.l_arm.straddle = 40;
@@ -42,12 +39,15 @@
 
 	man.stepOnGround();
 
-	// individual colours
-	man.l_elbow.setColor( 'yellow', 'black' );
-	man.l_wrist.setColor( 'orange' );
-	man.l_fingers.setColor( 'coral' );
-	man.r_knee.setColor( 'antiquewhite', 'black' );
-	man.l_nails.setColor( 'black' );
+	// overall colors
+	man.recolor( 'lightgreen', 'black', 'black', 'white', 'darkolivegreen', 'darkslategray', 'yellow' );
+
+	// individual colurs
+	man.l_elbow.recolor( 'yellow', 'black' );
+	man.l_wrist.recolor( 'orange' );
+	man.l_fingers.recolor( 'coral' );
+	man.r_knee.recolor( 'antiquewhite', 'black' );
+	man.l_nails.recolor( 'black' );
 
 	function animate( t ) {
 

diff --git a/docs/example-dynamic.html b/docs/example-dynamic.html
@@ -10,7 +10,7 @@
 	<script type="module">
 
 	import * as THREE from 'three';
-	import { Child, createScene, GROUND_LEVEL, scene } from 'mannequin';
+	import { Child, createScene, getGroundLevel, scene } from 'mannequin';
 
 	createScene( animate );
 
@@ -30,7 +30,7 @@
 	var material = new THREE.MeshPhongMaterial( { color: 'crimson', side: THREE.DoubleSide } );
 
 	var ball = new THREE.Mesh( geometry, material );
-	ball.position.set( 0, GROUND_LEVEL+BALL_SIZE, 0 );
+	ball.position.set( 0, getGroundLevel()+BALL_SIZE, 0 );
 	ball.receiveShadow = true;
 	ball.castShadow = true;
 

diff --git a/docs/example-touch-ground.html b/docs/example-touch-ground.html
@@ -10,7 +10,7 @@
 	<script type="module">
 
 	import * as THREE from 'three';
-	import { createScene, GROUND_LEVEL, Male } from 'mannequin';
+	import { createScene, getGroundLevel, Male } from 'mannequin';
 
 	createScene( animate );
 
@@ -80,7 +80,7 @@
 			man.l_ankle.point( 2, 2.5, -2 ).y,
 		);
 
-		man.position.y += ( GROUND_LEVEL - bottom );
+		man.position.y += ( getGroundLevel() - bottom );
 
 	}
 

diff --git a/docs/userguide-bg.md b/docs/userguide-bg.md
@@ -6,7 +6,7 @@
 ## <small><small>This document is also available in [English](userguide.md)</small></small>
 
 
-- **[Инициализация](#инициализация)** (<small>[Минимална програма](#минимална-програма) | [Инсталация](#инсталация) | [Видове фигури](#видове-фигури)</small>)
+- **[Инициализация](#инициализация)** (<small>[Минимална програма](#минимална-програма) | [Инсталация](#инсталация) | [Видове фигури](#видове-фигури) | [АПИ](#апи)</small>)
 - **[Части на тялото](#части-на-тялото)** (<small>[Централни части на тяло](#централни-части-на-тяло) | [Горни крайници](#горни-крайници) | [Долни крайници](#долни-крайници)</small>)
 - **[Поза на тялото](#поза-на-тялото)** (<small>[Статична поза](#статична-поза) | [Динамична поза](#динамична-поза) | [Работа с пози](#работа-с-пози)</small>)
 - **[Други функционалности](#други-функционалности)** (<small>[Собствени цветове](#собствени-цветове) | [Скриване на части от тялото](#скриване-на-части-от-тялото) | [Собствени части на тяло](#собствени-части-на-тяло) | [Глобална позиция](#глобална-позиция)</small>)
@@ -84,6 +84,16 @@ var kid = new Child();
 `Male` и `Female` придават мъжествена и женствена поза.
 
 
+### АПИ
+
+Библиотеката mannequin.js дефинира следните фукции и класове:
+
+* `getVersion()` &ndash; функция, връща текущата версия на mannequin.js като число; напр. 5.2
+* `getPostureVersion()` &ndash; функция, връща текущата версия на формата на данните, описващи поза
+* `getGroundLevel()` &ndash; функция, връща вертикалното положение на земята в метри
+
+
+
 
 # Части на тялото
 
@@ -432,13 +442,14 @@ mannequin.js предоставя основна функционалност з
 ### Собствени цветове
 
 По подразбиране всички фигури използват предварително дефиниран набор от
-глобални цветове за частите на тялото. Глобалните цветове се задават с `setColors` със седем като шест [Three.js цвята](https://threejs.org/docs/#api/en/math/Color)
-или [HTML/CSS имена на цветове](https ://www.w3schools.com/colors/colors_names.asp)
-параметъра за цвят на *глава*, *обувки*, *таз*, *стави*, *крайници*, *торс* и *нокти*:
+ цветове за частите на тялото. Цветовете за конкретна фигура се задават с метода
+ `recolor` със седем параметъра [Three.js цвята](https://threejs.org/docs/#api/en/math/Color)
+или [HTML/CSS имена на цветове](https://www.w3schools.com/colors/colors_names.asp).
+Тези цветове са за *глава*, *обувки*, *таз*, *стави*, *крайници*, *торс* и *нокти*:
 
 
 ``` javascript
-setColors(
+man.recolor(
     'antiquewhite',	// глава
     'gray',		    // обувки
     'antiquewhite',	// таз
@@ -449,34 +460,32 @@ setColors(
 );
 ```
 
-Глобалният цвят на ставите и крайниците се отнася до всички стави и всички
-крайници. Промяната на глобалните цветове има ефект, ако
-е направена преди създаването на фигури. Цветовете на частите от тялото могат
-да се променят индивидуално чрез метода `setColor` ([пример на живо](example-custom-colors.html)):
+Цветът на ставите и крайниците се отнася до всички стави и всички крайници.
+Цветовете на индивидуалните части от тялото могат да се променят чрез метода
+`recolor` на частите ([пример на живо](example-custom-colors.html)):
 
 [<img src="snapshots/example-custom-colors.jpg">](example-custom-colors.html)
 
 ``` javascript
-// глобални цветове
-setColors( 'lightgreen', 'black', 'black', 'white',
+var man = new Male();
+
+// общи цветове
+recolor( 'lightgreen', 'black', 'black', 'white',
            'darkolivegreen', 'darkslategray', 'yellow' );
 
-var man = new Male();
 :
 // индивидуални цветове
-man.l_elbow.setColor( 'yellow', 'black' );
-man.l_wrist.setColor( 'orange' );
-man.l_fingers.setColor( 'coral' );
-man.r_knee.setColor( 'antiquewhite', 'black' );
-man.l_nails.setColor( 'black' );
+man.l_elbow.recolor( 'yellow', 'black' );
+man.l_wrist.recolor( 'orange' );
+man.l_fingers.recolor( 'coral' );
+man.r_knee.recolor( 'antiquewhite', 'black' );
+man.l_nails.recolor( 'black' );
 ```
 
-Първият параметър на `setColor` е цветът на основния
-елемент на частта от тялото. Вторият параметър е цветът
-на сферичния елемент (ако има такъв).
+Първият параметър на `recolor` е цветът на основния елемент на частта от тялото.
+Вторият параметър е цветът на сферичния елемент (ако има такъв).
 
-Достъпът до върховете на пръстите се осъществява чрез
-`l_fingers.tips` и `r_fingers.tips`.
+Достъпът до върховете на пръстите се осъществява чрез `l_fingers.tips` и `r_fingers.tips`.
 
 
 

diff --git a/docs/userguide.md b/docs/userguide.md
@@ -5,7 +5,7 @@
 
 ## <small><small>Този документ е наличен и на [български език](userguide-bg.md)</small></small>
 
-- **[Initialization](#initialization)** (<small>[Minimal program](#minimal-program) | [Installation](#installation) | [Figure types](#figure-types)</small>) 
+- **[Initialization](#initialization)** (<small>[Minimal program](#minimal-program) | [Installation](#installation) | [Figure types](#figure-types) | [API](#api)</small>) 
 - **[Body parts](#body-parts)** (<small>[Central body parts](#central-body-parts) | [Upper limbs](#upper-limbs) | [Lower limbs](#lower-limbs)</small>)
 - **[Body posture](#body-posture)** (<small>[Static posture](#static-posture) | [Dynamic posture](#dynamic-posture) | [Working with postures](#working-with-postures)</small>)
 - **[Other functions](#other-functions)** (<small>[Custom colors](#custom-colors) | [Hiding body parts](#hiding-body-parts) | [Custom body parts](#custom-body-parts) | [Global position](#global-position)</small>)
@@ -83,6 +83,16 @@ male and female posture.
 
 
 
+### API
+
+The library mannequin.js defines the following functions and classes:
+
+* `getVersion()` &ndash; function, returns the current version of mannequin.js as a number; e.g. 5.2
+* `getPostureVersion()` &ndash; function, returns the current version of posture data format
+* `getGroundLevel()` &ndash; function, returns the vertical position of the ground in meters
+
+
+
 # Body parts
 
 All types of figures have the same structure. For example, the right arm of a figure is named `r_arm`. For some body parts mannequin.js uses the name of the joint &ndash; e.g. the left forearm is named `l_elbow`. Left and right body parts are always in respect to the figure, not to the viewer ([live example](example-body-parts.html)):
@@ -369,11 +379,13 @@ functionality for additional modification or accessing the figure.
 
 ### Custom colors
 
-By default, all figures use a predefined set of global colors for body parts. Global colors can be set with `setColors` with 7 [Three.js colors](https://threejs.org/docs/#api/en/math/Color) or [HTML/CSS color names](https://www.w3schools.com/colors/colors_names.asp) parameters for the colors of
+By default, all figures use a predefined set of colors for body parts.
+The colors of a specific figure can be set with the method `recolor` with 7 parameters that
+are [Three.js colors](https://threejs.org/docs/#api/en/math/Color) or [HTML/CSS color names](https://www.w3schools.com/colors/colors_names.asp). These colors are for the 
 *head*, *shoes*, *pelvis*, *joints*, *limbs*, *torso* and *nails*:
 
 ``` javascript
-setColors(
+man.recolor(
     'antiquewhite',	// head
     'gray',		    // shoes
     'antiquewhite',	// pelvis
@@ -384,26 +396,30 @@ setColors(
 );
 ```
 
-The global color of joints and limbs refers to all joints and all limbs. Modification of the global colors has effect if it is done before the creation of figure instances. Individual colors of body parts are set via the `setColor` method of each body part ([live example](example-custom-colors.html)):
+The color of joints and limbs refers to all joints and all limbs. 
+Individual colors of body parts are set via the `recolor` method of each body part ([live example](example-custom-colors.html)):
 
 [<img src="snapshots/example-custom-colors.jpg">](example-custom-colors.html)
 
 ``` javascript
-// global colors
-setColors( 'lightgreen', 'black', 'black', 'white',
+var man = new Male();
+
+// overall colors
+man.recolor( 'lightgreen', 'black', 'black', 'white',
            'darkolivegreen', 'darkslategray', 'yellow' );
 
-var man = new Male();
 :
 // individual colors
-man.l_elbow.setColor( 'yellow', 'black' );
-man.l_wrist.setColor( 'orange' );
-man.l_fingers.setColor( 'coral' );
-man.r_knee.setColor( 'antiquewhite', 'black' );
-man.l_nails.setColor( 'black' );
+man.l_elbow.recolor( 'yellow', 'black' );
+man.l_wrist.recolor( 'orange' );
+man.l_fingers.recolor( 'coral' );
+man.r_knee.recolor( 'antiquewhite', 'black' );
+man.l_nails.recolor( 'black' );
 ```
 
-The first parameter of `setColor` is the color of the main section of the body part. The second parameter is the color of the spherical section (if present).
+The first parameter of `recolor` of a body part is the color of the main section
+of the body part. The second parameter is the color of the spherical section
+(if present).
 
 The tips of the fingers are accessed via `l_fingers.tips` and `r_fingers.tips`.
 

diff --git a/src/bodies/Mannequin.js b/src/bodies/Mannequin.js
@@ -1,6 +1,6 @@
 import * as THREE from "three";
 
-import { GROUND_LEVEL, MANNEQUIN_POSTURE_VERSION } from "../globals.js";
+import { getGroundLevel, getPostureVersion } from "../globals.js";
 import { scene } from "../scene.js";
 import { Body } from "../organs/Body.js";
 import { Torso } from "../organs/Torso.js";
@@ -24,7 +24,7 @@ class MannequinPostureVersionError extends Error {
 
 	constructor( version ) {
 
-		super( 'Posture data version ' + version + ' is incompatible with the currently supported version ' + MANNEQUIN_POSTURE_VERSION + '.' );
+		super( 'Posture data version ' + version + ' is incompatible with the currently supported version ' + getPostureVersion() + '.' );
 		this.name = "IncompatibleMannequinError";
 
 	}
@@ -235,15 +235,15 @@ class Mannequin extends THREE.Group {
 			this.r_finger_4.posture,
 		];
 		return {
-			version: MANNEQUIN_POSTURE_VERSION,
+			version: getPostureVersion(),
 			data: posture,
 		};
 
 	} // Mannequin.posture
 
 	set posture( posture ) {
 
-		if ( posture.version != MANNEQUIN_POSTURE_VERSION )
+		if ( posture.version != getPostureVersion() )
 			throw new MannequinPostureVersionError( posture.version );
 
 		var i = 0;
@@ -300,13 +300,66 @@ class Mannequin extends THREE.Group {
 		this.position.y = 0;
 		this.updateMatrixWorld( true );
 		box.setFromObject( this, true );
-		this.position.y = -box.min.y + GROUND_LEVEL - 0.01;
+		this.position.y = -box.min.y + getGroundLevel() - 0.01;
 		this.rawHeight = box.max.y-box.min.y;
 		this.updateMatrixWorld( true );
 
 	}
 
 
+	recolor( head, shoes, pelvis, joints, limbs, torso, nails ) {
+
+		if ( head ) {
+
+			this.head.recolor( head );
+
+		}
+
+		if ( shoes ) {
+
+			this.l_ankle.recolor( shoes );
+			this.r_ankle.recolor( shoes );
+
+		}
+
+		if ( pelvis ) {
+
+			this.pelvis.recolor( pelvis );
+
+		}
+
+		if ( torso ) {
+
+			this.torso.recolor( torso, joints );
+
+		}
+
+		if ( nails ) {
+
+			this.l_nails.recolor( nails );
+
+		}
+
+		if ( limbs ) {
+
+			this.l_leg.recolor( limbs, joints );
+			this.l_knee.recolor( limbs, joints );
+			this.l_fingers.recolor( limbs, joints );
+			this.l_arm.recolor( limbs, joints );
+			this.l_elbow.recolor( limbs, joints );
+			this.l_wrist.recolor( limbs, joints );
+
+			this.r_leg.recolor( limbs, joints );
+			this.r_knee.recolor( limbs, joints );
+			this.r_fingers.recolor( limbs, joints );
+			this.r_arm.recolor( limbs, joints );
+			this.r_elbow.recolor( limbs, joints );
+			this.r_wrist.recolor( limbs, joints );
+
+		}
+
+	}
+
 } // Mannequin