<commit_before>/*
 *  Copyright (c) 2009-2012 jMonkeyEngine
 *  All rights reserved.
 * 
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are
 *  met:
 * 
 *  * Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 
 *  * Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 
 *  * Neither the name of 'jMonkeyEngine' nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 * 
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 *  TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 *  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 *  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 *  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 *  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 *  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 *  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 *  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 *  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package jme3tools.optimize;

import com.jme3.asset.AssetKey;
import com.jme3.asset.AssetManager;
import com.jme3.material.MatParamTexture;
import com.jme3.material.Material;
import com.jme3.math.Vector2f;
import com.jme3.scene.Geometry;
import com.jme3.scene.Mesh;
import com.jme3.scene.Spatial;
import com.jme3.scene.VertexBuffer;
import com.jme3.scene.VertexBuffer.Type;
import com.jme3.texture.Image;
import com.jme3.texture.Image.Format;
import com.jme3.texture.Texture;
import com.jme3.texture.Texture2D;
import com.jme3.util.BufferUtils;
import java.lang.reflect.InvocationTargetException;
import java.nio.ByteBuffer;
import java.nio.FloatBuffer;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * <b><code>TextureAtlas</code></b> allows combining multiple textures to one texture atlas.
 * <p>After the TextureAtlas has been created with a certain size, textures can be added for
 * freely chosen "map names". The textures are automatically placed on the atlas map and the
 * image data is stored in a byte array for each map name. Later each map can be retrieved as
 * a Texture to be used further in materials.</p>
 * <p>The first map name used is the "master map" that defines a new location on the atlas. Secondary
 * textures (other map names) have to reference one texture of the master map whose position is used
 * to position the texture on the secondary map. This is necessary as textures share texture coordinates
 * and thus need to be placed at the same location on both maps.<br/>
 * The helper methods that work with geometries handle the DiffuseMap or ColorMap as the master map and
 * additionally handle NormalMap and SpecularMap as secondary maps.</p>
 * <p>The texture asset key name for each tile as well as its location inside the atlas is stored
 * and a texture with an existing key name is never added more than once to the atlas. You can access
 * the information for each texture or geometry texture via helper methods.</p>
 * <p>For each texture name you can also change the texture coordinates of a mesh or geometry
 * to point at the new locations of the texture inside the atlas if the geometries texture
 * exists inside the atlas.</p>
 * <p>Note that models that use texture coordinates outside the 0-1 range (repeating/wrapping textures)
 * will not work correctly as their new coordinates leak into other parts of the atlas and thus display
 * other textures instead of repeating the texture.</p>
 * <p>Also note that textures are not scaled and the atlas needs to be large enough to hold all textures.
 * All methods that allow adding textures return false if the texture could not be added due to the
 * atlas being full. Furthermore secondary textures (normal, spcular maps etc. have to be the same size
 * as the main DiffuseMap texture.</p>
 * 
 * <p><b>Usage examples</b></p>
 * Create one geometry out of several geometries that are loaded from a j3o file:
 * <pre>
 * Node scene = assetManager.loadModel("Scenes/MyScene.j3o");
 * Geometry geom = TextureAtlas.makeAtlasBatch(scene);
 * rootNode.attachChild(geom);
 * </pre>
 * Create a texture atlas and change the texture coordinates of one geometry:
 * <pre>
 * Node scene = assetManager.loadModel("Scenes/MyScene.j3o");
 * //either auto-create from node:
 * TextureAtlas atlas = TextureAtlas.createAtlas(scene);
 * //or create manually by adding textures or geometries with textures
 * TextureAtlas atlas = new TextureAtlas(1024,1024);<commit_msg>- rephrase and clarify some TextureAtlas javadoc<commit_after>/*
 *  Copyright (c) 2009-2012 jMonkeyEngine
 *  All rights reserved.
 * 
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions are
 *  met:
 * 
 *  * Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 
 *  * Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 
 *  * Neither the name of 'jMonkeyEngine' nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 * 
 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 *  TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 *  PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 *  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 *  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 *  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 *  PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 *  LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 *  NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 *  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package jme3tools.optimize;

import com.jme3.asset.AssetKey;
import com.jme3.asset.AssetManager;
import com.jme3.material.MatParamTexture;
import com.jme3.material.Material;
import com.jme3.math.Vector2f;
import com.jme3.scene.Geometry;
import com.jme3.scene.Mesh;
import com.jme3.scene.Spatial;
import com.jme3.scene.VertexBuffer;
import com.jme3.scene.VertexBuffer.Type;
import com.jme3.texture.Image;
import com.jme3.texture.Image.Format;
import com.jme3.texture.Texture;
import com.jme3.texture.Texture2D;
import com.jme3.util.BufferUtils;
import java.lang.reflect.InvocationTargetException;
import java.nio.ByteBuffer;
import java.nio.FloatBuffer;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.TreeMap;
import java.util.logging.Level;
import java.util.logging.Logger;

/**
 * <b><code>TextureAtlas</code></b> allows combining multiple textures to one texture atlas.
 * 
 * <p>After the TextureAtlas has been created with a certain size, textures can be added for
 * freely chosen "map names". The textures are automatically placed on the atlas map and the
 * image data is stored in a byte array for each map name. Later each map can be retrieved as
 * a Texture to be used further in materials.</p>
 * 
 * <p>The first map name used is the "master map" that defines new locations on the atlas. Secondary
 * textures (other map names) have to reference a texture of the master map to position the texture
 * on the secondary map. This is necessary as the maps share texture coordinates and thus need to be
 * placed at the same location on both maps.</p>
 * 
 * <p>The helper methods that work with <code>Geometry</code> objects handle the <em>DiffuseMap</em> or <em>ColorMap</em> as the master map and
 * additionally handle <em>NormalMap</em> and <em>SpecularMap</em> as secondary maps.</p>
 * 
 * <p>The textures are referenced by their <b>asset key name</b> and for each texture the location
 * inside the atlas is stored. A texture with an existing key name is never added more than once
 * to the atlas. You can access the information for each texture or geometry texture via helper methods.</p>
 * 
 * <p>The TextureAtlas also allows you to change the texture coordinates of a mesh or geometry
 * to point at the new locations of its texture inside the atlas (if the texture exists inside the atlas).</p>
 * 
 * <p>Note that models that use texture coordinates outside the 0-1 range (repeating/wrapping textures)
 * will not work correctly as their new coordinates leak into other parts of the atlas and thus display
 * other textures instead of repeating the texture.</p>
 * 
 * <p>Also note that textures are not scaled and the atlas needs to be large enough to hold all textures.
 * All methods that allow adding textures return false if the texture could not be added due to the
 * atlas being full. Furthermore secondary textures (normal, spcular maps etc.) have to be the same size
 * as the main (e.g. DiffuseMap) texture.</p>
 * 
 * <p><b>Usage examples</b></p>
 * Create one geometry out of several geometries that are loaded from a j3o file:
 * <pre>
 * Node scene = assetManager.loadModel("Scenes/MyScene.j3o");
 * Geometry geom = TextureAtlas.makeAtlasBatch(scene);
 * rootNode.attachChild(geom);
 * </pre>
 * Create a texture atlas and change the texture coordinates of one geometry:
 * <pre>
 * Node scene = assetManager.loadModel("Scenes/MyScene.j3o");
 * //either auto-create from node:
 * TextureAtlas atlas = TextureAtlas.createAtlas(scene);
 * //or create manually by adding textures or geometries with textures
 * TextureAtlas atlas = new TextureAtlas(1024,1024);
{'fraction_non_alphanumeric': 0.07136087945413191, 'fraction_numerical': 0.007391963608794541, 'mean_word_length': 4.279139569784893, 'pattern_counts': {'":': 0, '<': 64, '<?xml version=': 0, '>': 64, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5320734', 'n_tokens_mistral': 2998, 'n_tokens_neox': 2819, 'n_words': 1340}