From f706ea98143f9ee3dd52f4bb42c0c90355d7cda6 Mon Sep 17 00:00:00 2001 From: Mike van Riel Date: Thu, 15 Aug 2024 08:03:38 +0200 Subject: [PATCH] First draft of a high-level concepts page to help developers grasp the core concepts of the application; which tie into the architecture in a subsequent chapter --- docs/docs/developers/core-concepts.md | 110 ++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 111 insertions(+) create mode 100644 docs/docs/developers/core-concepts.md diff --git a/docs/docs/developers/core-concepts.md b/docs/docs/developers/core-concepts.md new file mode 100644 index 0000000..bd76e0f --- /dev/null +++ b/docs/docs/developers/core-concepts.md @@ -0,0 +1,110 @@ +Whether you are plotting sensor telemetry, planning new building projects, or mapping underground utilities like cables +and pipes, Netherlands3D offers a versatile environment to bring your spatial data to life. This page introduces the key +concepts behind the platform, providing a foundation for understanding how the application is structured and how you can +leverage it for your projects. + +## Projects: The Canvas of Your Work + +In Netherlands3D, everything you interact with on the screen is part of a **Project**. A project encompasses all the data +layers, styles, and configurations that define your current view and can be saved or loaded as needed. Think of a +project as a snapshot of your work, capturing everything from the base map to the overlaid datasets, and allowing you to +revisit or share your work with others seamlessly. + +## Layers: The Foundation of Visualization + +In Netherlands3D, **Layers** are the fundamental components that bring spatial data to life on the map. Each layer +represents a specific dataset, determining not only what data is visualized but also how it appears. + +_While Rasterlayers and Vectorlayers are the primary types, there are also additional supporting layers like folders and +scenarios that help organize your project. However, the focus of this chapter will be on understanding the two main +types of layers and the nature of the datasets they contain._ + +### Understanding Datasets: Tiled vs. Fixed + +Before diving into the specifics of Raster and Vector layers, it's important to understand the concept of how datasets +are handled: **Tiled** versus **Fixed**. + +- **Tiled Datasets**: Tiling is a method used to optimize the performance of large datasets by breaking them down into +smaller, more manageable pieces called tiles. These tiles are loaded dynamically as needed, which is especially useful +when working with high-resolution data or when users need to navigate large geographical areas. Tiled datasets ensure +that only the necessary portions of data are loaded at any given time, reducing memory usage and enhancing performance. + +- **Fixed Datasets**: In contrast, fixed datasets are loaded in their entirety at once. This approach can be beneficial + when working with smaller datasets or when it's crucial to have immediate access to all the data without waiting for + it to stream. However, this method can be more demanding on system resources, particularly for large or complex + datasets. + +The choice between tiled and fixed datasets affects how the data is visualized and interacted with in Netherlands3D. +Whether a dataset is continuous (like elevation data) or discrete (like building footprints), it can be managed using +either a tiled or fixed approach. + +### Rasterlayers: Visualizing Continuous Data + +**Rasterlayers** are used to display continuous data across a geographic area, such as heatmaps, terrain models, or +aerial images. These layers are ideal for visualizing information that smoothly varies over space, like temperature +changes across a city or elevation in a landscape. + +In Netherlands3D, Rasterlayers are powerful for showing broad, sweeping patterns in your data. For example, if you want +to understand how pollution levels vary across a region, a Rasterlayer can provide a clear, visual representation of +these gradients. + +### Vectorlayers: Representing Discrete Data + +**Vectorlayers** are used to map specific features like buildings, roads, utilities, or zones. Each feature is +represented by points, lines, or polygons, and comes with attributes that describe it —such as the height of a building +or the type of road. + +Vectorlayers are essential for projects that require precise and detailed mapping. For instance, when planning new +infrastructure, you can use Vectorlayers to map out exactly where new roads or pipelines will go. Each feature can be +styled differently based on its attributes, making it easy to distinguish between different types of data. + +## Features: The Building Blocks of Layers + +In Netherlands3D, **Features** are the individual elements that make up a Vectorlayer and can also be present in certain +modern Rasterlayers. A feature represents a distinct geographical entity, such as a building, road, or zone, and can be +styled and visualized according to your project’s needs. + +Understanding features is crucial because they are the entities you interact with and analyze within a layer. +Whether you are drawing a map of utilities, defining zoning regulations, or visualizing sensor data, you are +essentially working with features. + +The ability to style and categorize these features, especially within the context of both vector and +hybrid raster layers, provides the flexibility to create detailed, informative, and visually compelling maps. + +### Features in Vectorlayers + +For Vectorlayers, features are the fundamental units. Each feature within a Vectorlayer has a specific geometry (point, +line, or polygon) and is tied to a set of attributes that describe its properties. For example, a Vectorlayer +representing buildings might have features corresponding to individual buildings, with attributes detailing their +height, function, or construction material. These features can be styled in various ways using the platform's styling +options, allowing you to differentiate between types of buildings, emphasize certain zones, or highlight critical +infrastructure. + +### Features in Rasterlayers: The Hybrid Approach + +Traditionally, Rasterlayers—such as overlay images or heatmaps—do not contain discrete features. They represent +continuous data spread across a grid, where each cell or pixel has a value but is not individually distinguished as a +feature. However, with advances in 3D mapping technology, a new hybrid approach has emerged. + +In this modern method, certain Rasterlayers, especially those involving 3D meshes, may incorporate features. For +example, a 3D terrain mesh (which is typically raster data) can have specific parts of the mesh categorized as features. +These features within a Rasterlayer might represent distinct geographical areas, such as regions of interest or zones +within a city, and can be individually styled and interacted with, similar to features in Vectorlayers. This blending of +raster and vector data allows for a more nuanced and detailed representation of the environment, offering new +possibilities for visualizing and analyzing spatial data. + +## Styles: Bringing Data to Life + +While layers define what data is displayed and where, Styles (or Symbology) determine how that data is visualized. +Styles control the visual appearance of layers, including colors, line thickness, transparency, and more. Similar to how +CSS styles HTML in web development, styles in Netherlands3D customize the visual representation of your spatial data. +Whether you want to highlight certain areas, differentiate between types of infrastructure, or simply make your map more +visually appealing, styles give you the flexibility to achieve your desired look and feel. + +## Conclusion + +Understanding these core concepts —Projects, Layers, Rasterlayers, Vectorlayers, Features, Styles, and the distinction +between Tiled and Fixed datasets— is crucial for effectively using Netherlands3D. These elements form the backbone of the +platform, allowing you to create, visualize, and interact with spatial data in a way that meets your project needs. As +you dive deeper into the application, these concepts will guide you in organizing your work and optimizing your use of +the platform’s powerful features. diff --git a/mkdocs.yml b/mkdocs.yml index e47d762..8d9036e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -52,6 +52,7 @@ draft_docs: | # Includes, starting with an underscore - https://www.mkdocs.org/user-guide/configuration/#not_in_nav not_in_nav: | _*.md + docs/developers/core-concepts.md site_name: "" # Empty on purpose for style purposes theme: