Namespace: reearth.layers
Description: This method is used to add a new layer to the reearth scene. This method is crucial for dynamically enhancing the scene with additional content layers, which can include elements such as imagery, data representations, or interactive widgets. The method takes a Layer object as its primary argument, which defines the characteristics and properties of the layer being added. Optionally, it can also take a parentId to specify the parent layer under which the new layer should be nested, and a creator identifier to track who created the layer.
Syntax: reearth.layers.add: (layer: Layer, parentId?: string, creator?: string) => string | undefined;
Parameters:
// An object that includes all the data and metadata necessary to create and manage a layer.
layer: Layer = { // The current layer being evaluated.
id: string; // A unique identifier for the layer.
type?: string; // (Optional) - The type of layer, which could indicate its function or the kind of content it holds.
pluginId?: string; // (Optional) - Identifier for a plugin associated with this layer, if applicable.
extensionId?: string; // (Optional) - Identifier for an extension that the layer might rely on.
title?: string; // (Optional) - A human-readable title for the layer.
property?: P; // (Optional) - Generic custom properties specific to the layer, can be of any type.
infobox?: `Infobox<IBP>`; // (Optional) - An infobox that can display additional interactive or informational content
isVisible?: boolean; // (Optional) - Flag indicating whether the layer is visible by default.
propertyId?: string; // (Optional) - A reference to an external property set that can be applied to the layer.
tags?: Tag[]; // (Optional) - An array of tags for categorization or searchability.
Tag = {
id: string; // A unique identifier for the tag.
label: string; // A human-readable label for the tag, which describes the category or characteristic that the tag represents, facilitating easier identification and selection in user interfaces.
tags?: Tag[]; //(Optional) - An optional array of additional Tag objects, allowing for the definition of a hierarchy of tags. This nested structure enables complex categorization schemes where tags can have sub-tags.
};
children?: Layer<P, IBP>[]; // (Optional) - An array of child layers, defining a hierarchy by making this layer a parent.
creator?: string; // (Optional) - Identifier of the user or system component that created the layer, if different from the one passing at the method call.
},
Return Value: string | undefined
id) of the newly added layer if the operation is successful, providing a reference that can be used for further manipulations or queries. If the operation fails, it returns undefined.Type defintion
interface Marker {
extensionId: string;
isVisible: boolean;
title: string;
property: {
default: {
location: {
lat: number;
lng: number;
}
}
}
}
Example with values
//1. Define a new layer
const newLayer = {
extensionId: "marker",
isVisible: true,
title: "Tokyo",
property: {
default: {
location: {
lat: 35.6895, // Tokyo co-ordinates
lng: 139.6917,
},
}
}
};
// Adds the new layer to the project
const newLayerId = reearth.layers.add(newLayer);
if (newLayerId) {
console.log("Layer added successfully with ID:", newLayerId);
} else {
console.log("Failed to add layer.");
}
Type defintion
interface PhotoOverlay {
extensionId: string; // 'photooverlay'
isVisible: boolean;
title: string;
property: {
default: {
location: {
lat: number;
lng: number;
};
camera: {
lat: number;
lng: number;
altitude: number;
heading: number;
pitch: number;
roll: number;
fov: number;
height: number;
};
image: string; // url pointing to the image resource
};
};
}
Example with values
// Define the photo-overlay layer
const photoOverlay = {
extensionId: "photooverlay",
isVisible: true,
title: "Photo Overlay",
property: {
default: {
location: {
lat: 35.6895, // Tokyo co-ordinates
lng: 139.6917,
},
camera: {
lat: -22.75433056252278,
lng: 117.91348383859152,
altitude: 12669683.27500231,
heading: 6.283185307179586,
pitch: -1.5668132233158247,
roll: 0,
fov: 1.0471975511965976,
height: 12669683.27500231
},
image: "<https://ucarecdn.com/338acbb2-fa76-4f0a-b1b2-488300ea42ff/-/preview/1740x1200>"
}
}
};
// Add the layer
reearth.layers.add(photoOverlay);
Type definition
interface Ellipsoid {
extensionId: string;
isVisible: boolean;
property: {
default: {
location: {
lat: number;
lng: number;
};
};
};
}
Example with values
// Define the ellipsoid layer
const ellipsoid = {
extensionId: 'ellipsoid',
isVisible: true,
property: {
default: {
location: {
lat: 35.652832, // Tokyo co-ordinates
lng: 139.839478
}
}
}
};
// Add the layer
reearth.layers.add(ellipsoid);
Type defintion
interface Model3d {
extensionId: string;
isVisible: boolean;
property: {
default: {
location: {
lat: number;
lng: number
}
height: number;
scale: number;
heading: number;
pitch: number;
roll: number;
model: string; // this has to be a url where the 3d model is hosted
}
}
}
Example with values
// define the 3D layer
const model3D = {
extensionId: 'model',
isVisible: true,
property: {
default: {
location: {
lat: 35.25633467636451, // Tokyo co-ordinates
lng: 139.8334732247744
},
height: 100,
scale: 1000,
heading: 0,
pitch: 0,
roll: 0,
model: '<https://api.test.reearth.dev/assets/01hz1dhrk537fpvjmxdd1zkn1w.gltf>' // 'Re:Earth' logo hosted publicly from test API workspace
}
}
}
// Add the layer
reearth.layers.add(model3D);
Type defintion
interface Tile3d {
extensionId: string;
isVisible: boolean;
property: {
default: {
tileset: string; // url of 3d tile .json file hosted publicly
}
}
}
Example with values
// Define a 3D tile. This is a 3D tile of Chiyoda yard building in Tokyo. The co-ordinates are Latitude: 35.69393005 Longitude: 139.75371138.
const title3d = {
extensionId: 'tileset',
isVisible: true,
property: {
default: {
tileset: '<https://assets.cms.plateau.reearth.io/assets/11/6d05db-ed47-4f88-b565-9eb385b1ebb0/13100_tokyo23-ku_2022_3dtiles%20_1_1_op_bldg_13101_chiyoda-ku_lod1/tileset.json>'
}
}
}
// Add the layer
reearth.layers.add(title3d);
Type defintion
interface coordinates {
lat: number;
lng: number;
height: number;
}
interface polygon {
extensionId: string;
isVisible: boolean;
property: {
default: {
fill: boolean;
fillColor: string; // RGB value
stroke: boolean;
strokeColor: string;
strokeWidth: number;
polygon: [
coordinates[];
]
}
}
}
Examples with values
// define the polygon
const polygon = {
extensionId: 'polygon',
isVisible: true,
property: {
default: {
fill: true,
fillColor: "#ffffffaa",
stroke: true,
strokeColor: "red",
strokeWidth: 10,
polygon: [
[
{ lat: 35.652832, lng: 139.839478, height: 100 }, // Polygon created over Tokyo region
{ lat: 36.652832, lng: 140.039478, height: 100 },
{ lat: 34.652832, lng: 141.839478, height: 100 },
],
],
},
},
};
// add the layer
reearth.layers.add(polygon);
Type definition
interface coordinates {
lat: number;
lng: number;
height: number;
}
interface polyline {
extensionId: string;
isVisible: boolean;
property: {
default: {
strokecolor: string;
strokewidth: number;
coordinates: coordinates[]
}
}
}
Example with values
// define the layer
const polyline = {
extensionId: 'polyline',
isVisible: true,
property: {
default: {
strokeColor: "#ccaa",
strokeWidth: 10,
coordinates: [
{ lat: 35.652832, lng: 139.839478, height: 100 }, // Polyline created over Tokyo region
{ lat: 36.652832, lng: 140.039478, height: 100 },
{ lat: 34.652832, lng: 141.839478, height: 100 },
]
}
}
};
// Add the layer
reearth.layers.add(polyline);
Description: This method provides a way to search for a layer within the reearth scene based on a custom search function. This method is crucial for locating a specific layer that matches certain criteria, such as attributes, properties, or conditions defined dynamically. The method takes a callback function that evaluates each layer and returns true for a layer that meets the desired conditions, facilitating targeted operations or analyses on specific parts of the scene.
Syntax: reearth.layers.find: ( fn: (layer: Layer, index: number, parents: Layer[]) => boolean, ) => Layer | undefined
Parameters:
// A callback function used to evaluate each layer within the scene. The function receives three arguments:
fn: (layer: Layer, index: number, parents: Layer[]) => boolean
// An object that includes all the data and metadata necessary to create and manage a layer.
layer: Layer = { // The current layer being evaluated.
id: string; // A unique identifier for the layer.
type?: string; // (Optional) - The type of layer, which could indicate its function or the kind of content it holds.
pluginId?: string; // (Optional) - Identifier for a plugin associated with this layer, if applicable.
extensionId?: string; // (Optional) - Identifier for an extension that the layer might rely on.
title?: string; // (Optional) - A human-readable title for the layer.
property?: P; // (Optional) - Generic custom properties specific to the layer, can be of any type.
infobox?: `Infobox<IBP>`; // (Optional) - An infobox that can display additional interactive or informational content
isVisible?: boolean; // (Optional) - Flag indicating whether the layer is visible by default.
propertyId?: string; // (Optional) - A reference to an external property set that can be applied to the layer.
tags?: Tag[]; // (Optional) - An array of tags for categorization or searchability.
children?: Layer<P, IBP>[]; // (Optional) - An array of child layers, defining a hierarchy by making this layer a parent.
creator?: string; // (Optional) - Identifier of the user or system component that created the layer, if different from the one passing at the method call.
},
index: number // The index of the current layer within its level of the hierarchy.
parents: Layer[] // An array of parent layers, providing context about the layer's location within the hierarchy.
// The function should return true for a layer that matches the search criteria, indicating that this is the layer to be returned.
boolean
Return Value: Layer | undefined
Layer object that satisfies the provided testing function. If no layer meets the criteria, the function returns undefinedExamples Usage:
//1. Define a search function to find the first visible layer
const searchFunction = (layer, index, parents) => {
return layer.isVisible === true;
};
// Use the find method to locate the first visible layer
const foundLayer = reearth.layers.find(searchFunction);
// Log the result or handle the case where no layer is found
if (foundLayer) {
console.log(`Found visible layer with ID: ${foundLayer.id}`);
} else {
console.log("No visible layer found.");
}
//2. Search for the first layer that is a marker with the title "Re:Earth" and assign it to a variable.
const markerThatTitleIsReearth = reearth.layers.find(
layer => layer.type === "marker" && layer.title === "Re:Earth"
);
Description: This method performs a comprehensive search through all layers in a project to find and return an array of layers that match a specified condition. This method takes a callback function that is applied to each layer in the project.
Syntax: reearth.layers.findAll: (layer: Layer, index: number, parents: Layer>[]) => boolean) => Layer[]
Parameters:
// A callback function used to evaluate each layer within the scene. The function receives three arguments:
fn: (layer: Layer, index: number, parents: Layer[]) => boolean
// An object that includes all the data and metadata necessary to create and manage a layer.
layer: Layer = { // The current layer being evaluated.
id: string; // A unique identifier for the layer.
type?: string; // (Optional) - The type of layer, which could indicate its function or the kind of content it holds.
pluginId?: string; // (Optional) - Identifier for a plugin associated with this layer, if applicable.
extensionId?: string; // (Optional) - Identifier for an extension that the layer might rely on.
title?: string; // (Optional) - A human-readable title for the layer.
property?: P; // (Optional) - Generic custom properties specific to the layer, can be of any type.
infobox?: `Infobox<IBP>`; // (Optional) - An infobox that can display additional interactive or informational content
isVisible?: boolean; // (Optional) - Flag indicating whether the layer is visible by default.
propertyId?: string; // (Optional) - A reference to an external property set that can be applied to the layer.
tags?: Tag[]; // (Optional) - An array of tags for categorization or searchability.
children?: Layer<P, IBP>[]; // (Optional) - An array of child layers, defining a hierarchy by making this layer a parent.
creator?: string; // (Optional) - Identifier of the user or system component that created the layer, if different from the one passing at the method call.
},
index: number // The index of the current layer within its level of the hierarchy.
parents: Layer[] // An array of parent layers, providing context about the layer's location within the hierarchy.
// The function should return true for a layer that matches the search criteria, indicating that this is the layer to be returned.
boolean
Return Value: Layer[]
Layer objects that satisfy the conditions specified by the callback function. If no layers meet the criteria, it returns an empty array.Example Usage:
//1. Define a search function to find all layers with a specific visibility setting
const searchVisibleLayers = (layer) => layer.isVisible;
// Use the findAll method to get all visible layers
const visibleLayers = reearth.layers.findAll(searchVisibleLayers);
// Output the IDs of the found layers
console.log("Visible layers found:", visibleLayers.map(layer => layer.id));
//2. Function to find all visible layers
const visibleLayers = reearth.layers.findAll((layer) => layer.isVisible);
// Logging the titles of all found layers
visibleLayers.forEach(layer => {
console.log("Visible layer:", layer.title);
});
// Function to find layers by a specific pluginId
const pluginLayers = reearth.layers.findAll(layer => layer.pluginId === "examplePluginId");
console.log("Layers using examplePluginId:", pluginLayers.map(layer => layer.title));
//3. Filter out layers where the type is "resource" and the title is exactly "CZML".
let filteredLayers = reearth.layers.findAll(layer => (layer.type === "resource" && layer.title === 'CZML'))
// Log the array of filtered layers to the console. This array contains all layers that meet the specified conditions.
console.log("filteredLayers: ", filteredLayers);
Description: This method is designed to retrieve a specific layer object based on its unique identifier (ID). This method is essential for directly accessing a layer when its ID is known, allowing for efficient and precise operations such as editing properties, toggling visibility, or analyzing layer-specific data. It simplifies the process of interacting with individual layers by providing a direct path to them without the need to search or iterate through the entire layer hierarchy. This method takes a single string parameter, which is the ID of the layer you want to find.
Syntax: reearth.layers.findById: (id: string) => Layer | undefined;
Parameters:
id: string //The unique identifier of the layer that is being searched for within the scene.
Return Value: Layer | undefined
Layer object if a layer with the specified ID is found. If no layer matches the provided ID, it returns undefined.Example Usage:
//1. Directly search with a specific ID
reearth.layers.findById("01hrv2ddxmg7a64xw9mdq81f6k")
//2. Define the layer ID you are searching for
const targetLayerId = "01hsjd48a8cv90z5hmv94c7ff1";
// Attempt to find the layer by its ID
const layer = reearth.layers.findById(targetLayerId);
// Check if the layer was found and log the result or handle it accordingly
if (layer) {
console.log(`Layer found: ${layer.title}`);
} else {
console.log("No layer found with the specified ID:", targetLayerId);
}
//3. Function to retrieve a layer by its ID and log its details
function logLayerDetails(layerId) {
const layer = reearth.layers.findById(layerId);
if (layer) {
console.log("Found layer:", layer);
} else {
console.log("No layer found with ID:", layerId);
}
}
// Example of using the function with a specific layer ID
logLayerDetails("01hsjd48a8cv90z5hmv94c7ff1");
Description: This method allows for the retrieval of multiple layers from the reearth scene simultaneously based on an array of layer IDs. This method is particularly useful for applications that need to interact with or manipulate several specific layers at once, such as batch updating properties, applying effects, or managing group visibility. This method accepts a spread of string arguments, each representing the ID of a layer, and returns an array where each element corresponds to a Layer object or undefined.
Syntax: reearth.layers.findByIds: (...id: string[]) => (Layer | undefined)[];
Parameters:
...id: string[] // A spread of string arguments, each representing the unique identifier of a layer to be retrieved. This allows for flexible input of one or multiple IDs.
// An object that includes all the data and metadata necessary to create and manage a layer.
layer: Layer = { // The current layer being evaluated.
id: string; // A unique identifier for the layer.
type?: string; // (Optional) - The type of layer, which could indicate its function or the kind of content it holds.
pluginId?: string; // (Optional) - Identifier for a plugin associated with this layer, if applicable.
extensionId?: string; // (Optional) - Identifier for an extension that the layer might rely on.
title?: string; // (Optional) - A human-readable title for the layer.
property?: P; // (Optional) - Generic custom properties specific to the layer, can be of any type.
infobox?: `Infobox<IBP>`; // (Optional) - An infobox that can display additional interactive or informational content
isVisible?: boolean; // (Optional) - Flag indicating whether the layer is visible by default.
propertyId?: string; // (Optional) - A reference to an external property set that can be applied to the layer.
tags?: Tag[]; // (Optional) - An array of tags for categorization or searchability.
children?: Layer<P, IBP>[]; // (Optional) - An array of child layers, defining a hierarchy by making this layer a parent.
creator?: string; // (Optional) - Identifier of the user or system component that created the layer, if different from the one passing at the method call.
},
Return Value: (Layer | undefined)[]
Layer objects or undefined for each input ID, depending on whether the layer with that ID exists in the scene. Each position in the returned array corresponds directly to the position of the ID in the input list, maintaining order consistency. If a layer with a given ID does not exist, the method returns undefined at that position in the array.Example Usage:
//1. Function to retrieve and log details of multiple layers by their IDs
function logMultipleLayerDetails(...layerIds) {
const layers = reearth.layers.findByIds(...layerIds);
layers.forEach((layer, index) => {
if (layer) {
console.log(`Layer ${index + 1} found:`, layer);
} else {
console.log(`Layer ${index + 1} not found for ID: ${layerIds[index]}`);
}
});
}
// Example call to function with multiple layer IDs
logMultipleLayerDetails("01hrv2ddxmg7a64xw9mdq81f6k", "01hsjd48a8cv90z5hmv94c7ff1");
//2. Define an array of layer IDs to be searched
const layerIds = ["01hrv2ddxmg7a64xw9mdq81f6k", "01hsjd48a8cv90z5hmv94c7ff1"];
// Retrieve the layers by their IDs
const layers = reearth.layers.findByIds(...layerIds);
// Process the results, handling both found and not found cases
layers.forEach((layer, index) => {
if (layer) {
console.log(`Layer found: ID = ${layer.id}, Title = ${layer.title}`);
} else {
console.log(`No layer found for ID: ${layerIds[index]}`);
}
});
Description: This method provides a way to retrieve all layers associated with one or more specified tags. This function accepts a spread of string arguments, each representing the ID of a tag, and returns an array of Layer objects that match any of the provided tag IDs. This method is essential for filtering and managing layers based on categorization tags, which can be used to group layers by themes, types, or any other organizational criteria.
Syntax: reearth.layers.findByTags: (...tagIds: string[]) => Layer[]
Parameters:
...tagIds: string[] // A spread of string parameters, where each string is the ID of a tag used to categorize or identify layers.
// An object that includes all the data and metadata necessary to create and manage a layer.
layer: Layer = { // The current layer being evaluated.
id: string; // A unique identifier for the layer.
type?: string; // (Optional) - The type of layer, which could indicate its function or the kind of content it holds.
pluginId?: string; // (Optional) - Identifier for a plugin associated with this layer, if applicable.
extensionId?: string; // (Optional) - Identifier for an extension that the layer might rely on.
title?: string; // (Optional) - A human-readable title for the layer.
property?: P; // (Optional) - Generic custom properties specific to the layer, can be of any type.
infobox?: `Infobox<IBP>`; // (Optional) - An infobox that can display additional interactive or informational content
isVisible?: boolean; // (Optional) - Flag indicating whether the layer is visible by default.
propertyId?: string; // (Optional) - A reference to an external property set that can be applied to the layer.
tags?: Tag[]; // (Optional) - An array of tags for categorization or searchability.
children?: Layer<P, IBP>[]; // (Optional) - An array of child layers, defining a hierarchy by making this layer a parent.
creator?: string; // (Optional) - Identifier of the user or system component that created the layer, if different from the one passing at the method call.
},
Return Value: Layer[]
Layer objects that are associated with any of the specified tags. If no layers match the provided tags, an empty array is returned.Example Usage: