MTLLoader improvements (#8689)

* MTLLoader: Deprecate setBaseUrl in favor or better named setTexturePath.
Make sure MaterialCreator.baseUrl is not undefined if no path/texture path is set.

* MTLLoader: Automatically resolve texture base path from .mtl source URL if not explicitly set with setPath or setTexturePath.
The URL parameter to .parse(text, url) is passed in if you use .load(). For external use it is optional and preserves earlier behavior if not passed in.

* MTLLoader: Use single quotes consistently. Make params object property setting easier to read.

* MTLLoader: Don't overwrite already found diffuse texture like is done with bump map. This might change behavior for bad materials that define 'map_kd' multiple times.

* MTLLoader: Remaining double quotes to single ticks, also in documentation.

* MTLLoader: Remove auto resolving base path from .mtl source URL.
Add documentation to load and other important functions.
Remove now redundant call to .setBaseUrl in obj/mtl loader example. setPath is enough if the .mtl and textures have the same base path (documented).

* MTLLoader: Dont break parsed texture references that are already absolute URLs.

* MTLLoader: Fix doc typos.

* MTLLoader: Move utility function inside the function that uses it.

* MTLLoader: Use case insensitive regexp instead for abs URL checks.

examples/js/loaders/MTLLoader.js

@@ -14,6 +14,19 @@ THREE.MTLLoader.prototype = {
 
 	constructor: THREE.MTLLoader,
 
+	/**
+	 * Loads and parses a MTL asset from a URL.
+	 *
+	 * @param {String} url - URL to the MTL file.
+	 * @param {Function} [onLoad] - Callback invoked with the loaded object.
+	 * @param {Function} [onProgress] - Callback for download progress.
+	 * @param {Function} [onError] - Callback for download errors.
+	 *
+	 * @see setPath setTexturePath
+	 *
+	 * @note In order for relative texture references to resolve correctly
+	 * you must call setPath and/or setTexturePath explicitly prior to load.
+	 */
 	load: function ( url, onLoad, onProgress, onError ) {
 
 		var scope = this;
@@ -28,17 +41,47 @@ THREE.MTLLoader.prototype = {
 
 	},
 
-	setPath: function ( value ) {
+	/**
+	 * Set base path for resolving references.
+	 * If set this path will be prepended to each loaded and found reference.
+	 *
+	 * @see setTexturePath
+	 * @param {String} path
+	 *
+	 * @example
+	 *     mtlLoader.setPath( 'assets/obj/' );
+	 *     mtlLoader.load( 'my.mtl', ... );
+	 */
+	setPath: function ( path ) {
+
+		this.path = path;
+
+	},
+
+	/**
+	 * Set base path for resolving texture references.
+	 * If set this path will be prepended found texture reference.
+	 * If not set and setPath is, it will be used as texture base path.
+	 *
+	 * @see setPath
+	 * @param {String} path
+	 *
+	 * @example
+	 *     mtlLoader.setPath( 'assets/obj/' );
+	 *     mtlLoader.setTexturePath( 'assets/textures/' );
+	 *     mtlLoader.load( 'my.mtl', ... );
+	 */
+	setTexturePath: function( path ) {
 
-		this.path = value;
+		this.texturePath = path;
 
 	},
 
-	setBaseUrl: function( value ) {
+	setBaseUrl: function( path ) {
 
-		// TODO: Merge with setPath()? Or rename to setTexturePath?
+		console.warn( 'THREE.MTLLoader: .setBaseUrl() is deprecated. Use .setTexturePath( path ) for texture path or .setPath( path ) for general base path instead.' );
 
-		this.baseUrl = value;
+		this.setTexturePath( path );
 
 	},
 
@@ -55,13 +98,19 @@ THREE.MTLLoader.prototype = {
 	},
 
 	/**
-	 * Parses loaded MTL file
-	 * @param text - Content of MTL file
+	 * Parses a MTL file.
+	 *
+	 * @param {String} text - Content of MTL file
 	 * @return {THREE.MTLLoader.MaterialCreator}
+	 *
+	 * @see setPath setTexturePath
+	 *
+	 * @note In order for relative texture references to resolve correctly
+	 * you must call setPath and/or setTexturePath explicitly prior to parse.
 	 */
 	parse: function ( text ) {
 
-		var lines = text.split( "\n" );
+		var lines = text.split( '\n' );
 		var info = {};
 		var delimiter_pattern = /\s+/;
 		var materialsInfo = {};
@@ -83,10 +132,10 @@ THREE.MTLLoader.prototype = {
 			var key = ( pos >= 0 ) ? line.substring( 0, pos ) : line;
 			key = key.toLowerCase();
 
-			var value = ( pos >= 0 ) ? line.substring( pos + 1 ) : "";
+			var value = ( pos >= 0 ) ? line.substring( pos + 1 ) : '';
 			value = value.trim();
 
-			if ( key === "newmtl" ) {
+			if ( key === 'newmtl' ) {
 
 				// New material
 
@@ -95,7 +144,7 @@ THREE.MTLLoader.prototype = {
 
 			} else if ( info ) {
 
-				if ( key === "ka" || key === "kd" || key === "ks" ) {
+				if ( key === 'ka' || key === 'kd' || key === 'ks' ) {
 
 					var ss = value.split( delimiter_pattern, 3 );
 					info[ key ] = [ parseFloat( ss[ 0 ] ), parseFloat( ss[ 1 ] ), parseFloat( ss[ 2 ] ) ];
@@ -110,7 +159,7 @@ THREE.MTLLoader.prototype = {
 
 		}
 
-		var materialCreator = new THREE.MTLLoader.MaterialCreator( this.baseUrl, this.materialOptions );
+		var materialCreator = new THREE.MTLLoader.MaterialCreator( this.texturePath || this.path, this.materialOptions );
 		materialCreator.setCrossOrigin( this.crossOrigin );
 		materialCreator.setManager( this.manager );
 		materialCreator.setMaterials( materialsInfo );
@@ -137,7 +186,7 @@ THREE.MTLLoader.prototype = {
 
 THREE.MTLLoader.MaterialCreator = function( baseUrl, options ) {
 
-	this.baseUrl = baseUrl;
+	this.baseUrl = baseUrl || '';
 	this.options = options;
 	this.materialsInfo = {};
 	this.materials = {};
@@ -299,6 +348,19 @@ THREE.MTLLoader.MaterialCreator.prototype = {
 
 		};
 
+		var resolveURL = function ( baseUrl, url ) {
+
+			if ( typeof url !== 'string' || url === '' )
+				return '';
+
+			// Absolute URL
+			if ( /^https?:\/\//i.test( url ) ) {
+				return url;
+			}
+
+			return baseUrl + url;
+		};
+
 		for ( var prop in mat ) {
 
 			var value = mat[ prop ];
@@ -313,14 +375,14 @@ THREE.MTLLoader.MaterialCreator.prototype = {
 
 					// Diffuse color (color under white light) using RGB values
 
-					params[ 'color' ] = new THREE.Color().fromArray( value );
+					params.color = new THREE.Color().fromArray( value );
 
 					break;
 
 				case 'ks':
 
 					// Specular color (color when light is reflected from shiny surface) using RGB values
-					params[ 'specular' ] = new THREE.Color().fromArray( value );
+					params.specular = new THREE.Color().fromArray( value );
 
 					break;
 
@@ -328,9 +390,11 @@ THREE.MTLLoader.MaterialCreator.prototype = {
 
 					// Diffuse texture map
 
-					params[ 'map' ] = this.loadTexture( this.baseUrl + value );
-					params[ 'map' ].wrapS = this.wrap;
-					params[ 'map' ].wrapT = this.wrap;
+					if ( params.map ) break; // Keep the first encountered texture
+
+					params.map = this.loadTexture( resolveURL( this.baseUrl, value ) );
+					params.map.wrapS = this.wrap;
+					params.map.wrapT = this.wrap;
 
 					break;
 
@@ -339,7 +403,7 @@ THREE.MTLLoader.MaterialCreator.prototype = {
 					// The specular exponent (defines the focus of the specular highlight)
 					// A high exponent results in a tight, concentrated highlight. Ns values normally range from 0 to 1000.
 
-					params[ 'shininess' ] = parseFloat( value );
+					params.shininess = parseFloat( value );
 
 					break;
 
@@ -347,8 +411,8 @@ THREE.MTLLoader.MaterialCreator.prototype = {
 
 					if ( value < 1 ) {
 
-						params[ 'opacity' ] = value;
-						params[ 'transparent' ] = true;
+						params.opacity = value;
+						params.transparent = true;
 
 					}
 
@@ -358,8 +422,8 @@ THREE.MTLLoader.MaterialCreator.prototype = {
 
 					if ( value > 0 ) {
 
-						params[ 'opacity' ] = 1 - value;
-						params[ 'transparent' ] = true;
+						params.opacity = 1 - value;
+						params.transparent = true;
 
 					}
 
@@ -370,11 +434,11 @@ THREE.MTLLoader.MaterialCreator.prototype = {
 
 					// Bump texture map
 
-					if ( params[ 'bumpMap' ] ) break; // Avoid loading twice.
+					if ( params.bumpMap ) break; // Keep the first encountered texture
 
-					params[ 'bumpMap' ] = this.loadTexture( this.baseUrl + value );
-					params[ 'bumpMap' ].wrapS = this.wrap;
-					params[ 'bumpMap' ].wrapT = this.wrap;
+					params.bumpMap = this.loadTexture( resolveURL( this.baseUrl, value ) );
+					params.bumpMap.wrapS = this.wrap;
+					params.bumpMap.wrapT = this.wrap;
 
 					break;
 
@@ -390,7 +454,6 @@ THREE.MTLLoader.MaterialCreator.prototype = {
 
 	},
 
-
 	loadTexture: function ( url, mapping, onLoad, onProgress, onError ) {
 
 		var texture;

examples/webgl_loader_obj_mtl.html

@@ -88,7 +88,6 @@
 				THREE.Loader.Handlers.add( /\.dds$/i, new THREE.DDSLoader() );
 
 				var mtlLoader = new THREE.MTLLoader();
-				mtlLoader.setBaseUrl( 'obj/male02/' );
 				mtlLoader.setPath( 'obj/male02/' );
 				mtlLoader.load( 'male02_dds.mtl', function( materials ) {