### Example OWL taxonomy file structure Source: https://context7.com/metason/spatialreasoner/llms.txt An example of an OWL taxonomy file defining classes, their labels, subclass relationships (rdfs:subClassOf), and synonyms (skos:altLabel). ```xml Furniture Seating Chair seat armchair Bed double bed ``` -------------------------------- ### Connectivity Graph Example Source: https://github.com/metason/spatialreasoner/blob/main/README.md Illustrates the connectivity between spatial elements like walls and floors. Helps in understanding spatial arrangements. ```mermaid graph TD; wall2 <-- by --> wall1 wall2 <-- by --> wall3 wall3 <-- by --> wall4 wall4 <-- by --> wall1 door -- in --> wall1 window -- in --> wall2 picture -- at --> wall4 wall1 -- on --> floor wall2 -- on --> floor wall3 -- on --> floor wall4 -- on --> floor table -- on --> floor ``` -------------------------------- ### Example Spatial Inference Pipeline Source: https://github.com/metason/spatialreasoner/blob/main/README.md Demonstrates a basic spatial inference pipeline with filter, pick, and log operations. ```text filter(volume > 0.4) | pick(left AND above) | log() ``` -------------------------------- ### Example 3D Inference Pipeline Source: https://github.com/metason/spatialreasoner/blob/main/README.md This is an example of a sequence of inference operations in a pipeline. It demonstrates filtering, picking, and sorting spatial data. ```plaintext deduce(topology) | filter(id == 'ego') | pick(disjoint) | filter(volume > 0.5 AND NOT moving) | sort(disjoint.delta <) ``` -------------------------------- ### Find furniture near the user in Swift Source: https://context7.com/metason/spatialreasoner/llms.txt Example pipeline to find interactable furniture objects near the user, sorted by proximity. ```swift // Example 1: Find furniture near the user that they can interact with let findInteractables = """ deduce(topology visibility) | filter(id == 'user') | pick(near AND infront AND disjoint) | filter(type == 'furniture' AND visible) | sort(disjoint.delta <) | slice(1..5) """ ``` -------------------------------- ### adjust() - Configuring Spatial Parameters Source: https://context7.com/metason/spatialreasoner/llms.txt The adjust() operation configures reasoning parameters at the start of a pipeline to fit the actual context, environment, and dominant object size. Settings include nearby radius calculation, sector size, and maximum deviation tolerances. ```APIDOC ## adjust() - Configuring Spatial Parameters ### Description The adjust() operation configures reasoning parameters at the start of a pipeline to fit the actual context, environment, and dominant object size. Settings include nearby radius calculation, sector size, and maximum deviation tolerances. ### Method Not explicitly defined, but used within a pipeline string. ### Endpoint Not applicable, used as part of a pipeline. ### Parameters This operation takes various keyword-value pairs to configure parameters. Examples include: - `max gap` (float) - Maximum gap tolerance. - `sector` (string) - Sector schema (e.g., 'dimension', 'fixed'). - `nearby` (string, float) - Nearby calculation schema and limit (e.g., 'fixed 1.2', 'limit 4.0'). - `thin ratio` (float) - Ratio for thin objects. ### Request Example ```swift let pipeline = "adjust(max gap 0.05; sector dimension; thin ratio 10.0; nearby limit 4.0)" ``` ### Response This operation modifies the internal state of the SpatialReasoner. No direct response is returned, but subsequent operations are affected. ### Available Schemas - **Nearby schemas**: `fixed`, `circle`, `sphere`, `perimeter`, `area` - **Sector schemas**: `fixed`, `dimension`, `perimeter`, `area`, `nearby` ``` -------------------------------- ### Spatial Relation Graph Example Source: https://github.com/metason/spatialreasoner/blob/main/README.md Visualizes the relationships between spatial objects using a directed graph. Useful for understanding object interactions. ```mermaid graph LR; subj obj ego obj -- left --> subj obj -- seenright --> subj ego -- left --> subj subj -- seenleft --> obj ego -- right --> obj obj -- right --> ego ``` -------------------------------- ### Enable Similarity Deduction Source: https://github.com/metason/spatialreasoner/blob/main/Relations.md Call `deduce(similarity)` at the start of the pipeline or set `deduce.similarity = true` to enable similarity relations. ```python deduce(similarity) ``` ```python deduce.similarity = true ``` -------------------------------- ### Enable Comparability Deduction Source: https://github.com/metason/spatialreasoner/blob/main/Relations.md Call `deduce(comparability)` at the start of the pipeline or set `deduce.comparability = true` to enable comparability relations. ```python deduce(comparability) ``` ```python deduce.comparability = true ``` -------------------------------- ### Swift - Adjust spatial parameters Source: https://context7.com/metason/spatialreasoner/llms.txt Use adjust() to configure reasoning parameters like nearby radius, sector size, and deviation tolerances at the start of a pipeline. Supports multiple settings in a single call. ```swift // Swift - Adjust spatial parameters let sr = SpatialReasoner() sr.load(objects) // Set max deviation for touch detection (5cm gap tolerance) let pipeline1 = "adjust(max gap 0.05) | select(on ? type == 'floor')" // Configure nearby calculation schema with fixed radius let pipeline2 = "adjust(nearby fixed 1.2) | pick(near)" // Use dimension-based sectors let pipeline3 = "adjust(sector dimension) | pick(leftside)" // Multiple settings in one adjust call let pipeline4 = """ adjust(max gap 0.05; sector dimension; thin ratio 10.0; nearby limit 4.0) | deduce(topology connectivity) | filter(type == 'furniture') | pick(near AND left) """ sr.run(pipeline4) // Available nearby schemas: fixed, circle, sphere, perimeter, area // Available sector schemas: fixed, dimension, perimeter, area, nearby ``` -------------------------------- ### Generate Objects at Connectivity Relations Source: https://github.com/metason/spatialreasoner/blob/main/README.md Use the `produce(by:)` rule to generate new spatial objects at specific connectivity relations between existing objects. This example creates corner objects where walls meet. ```SpatialReasoning filter(type == 'wall') | produce(by : label = 'corner'; h = 0.02) ``` -------------------------------- ### Enable Geography Relations Source: https://github.com/metason/spatialreasoner/blob/main/Relations.md Call `deduce(geography)` at the start of the pipeline or set `deduce.geography = true` to enable geography relation derivations. ```python deduce(geography) ``` ```python deduce.geography = true ``` -------------------------------- ### Spatial Relation Terminology Example Source: https://github.com/metason/spatialreasoner/blob/main/Taxonomy.md This JSON object defines a spatial relation term, including its code, verbal predicate, category, antonym, inverse, preposition, synonyms, and verb. It serves as a foundational element for integrating spatial reasoning with NLP and LLM. ```json { "code" : "seenleft", "predicate" : "seen left", "category" : "visibility", "antonym" : "", "inverse" : "seen right", "preposition" : "of", "synonyms" : "visible to the left", "verb" : "is" } ``` -------------------------------- ### Spatial Reasoner Usage in C# Source: https://github.com/metason/spatialreasoner/blob/main/README.md Demonstrates initializing SpatialObjects, loading them into the SpatialReasoner, and running a pipeline. Also shows queued methods and extension methods for common operations. ```csharp var st = new SpatialTerms(); var obj1 = new SpatialObject(id: "1", position: new SCNVector3(x: -1.5f, y: 1.2f, z: 0), width: 0.1f, height: 1.0f, depth: 0.1f); var obj2 = new SpatialObject(id: "2", position: new SCNVector3(x: 0, y: 0, z: 0), width: 0.8f, height: 1.0f, depth: 0.6f); var obj3 = new SpatialObject(id: "3", position: new SCNVector3(x: 0, y: 0, z: 1.6f), width: 0.8f, height: 0.8f, depth: 0.8f); obj3.Angle = (float)(Math.PI / 2.0); SpatialObject[] objs = [obj1, obj2, obj3] //Full pipeline input var sr = new SpatialReasoner(); sr.Load(objs); var pipeline = "filter(volume > 0.4) | pick(Left OR Above) | log()"; if (sr.Run(pipeline)) { Console.WriteLine(string.Join('\n', sr.Result)); } //Queued methods SpatialReasoner.Create().Load(objs).Filter("volume>0.4").Pick("Left OR Above").CLog(); //Extensions Methods on IEnumerable Console.WriteLine(string.Join('\n', SpatialReasoner.Create().Load(objs).Where(so => so.Volume > 0.4).ToList())); ``` -------------------------------- ### Get Second Left Object Source: https://github.com/metason/spatialreasoner/blob/main/README.md Finds the second spatial object of type 'picture' that is to the 'ahead' and 'left' of the 'ego' object, sorting by disjoint delta and slicing to get the second object. ```plaintext deduce(topology) | filter(id == 'ego') | pick(ahead AND left AND disjoint) | filter(type == 'picture') | sort(disjoint.delta > 2) | slice(2) ``` -------------------------------- ### Initialize and Run Pipeline in Python Source: https://context7.com/metason/spatialreasoner/llms.txt Initialize the SpatialReasoner, load objects, and execute a pipeline. Processes results and prints object IDs. ```python # Python - Initialize reasoner and run pipeline sr = SpatialReasoner() sr.load([lamp, table, chair]) pipeline = "filter(volume > 0.4) | pick(left AND above) | log()" if sr.run(pipeline): result = sr.result() for obj in result: print(f"Found: {obj.id}") ``` -------------------------------- ### Initialize and Run Spatial Reasoner in Python Source: https://github.com/metason/spatialreasoner/blob/main/README.md Map 3D entities to SpatialObject instances, load them into the SpatialReasoner, and run a pipeline for inference. The result can be accessed after the pipeline execution. ```python obj1 = SpatialObject( "1", position=Vector3(-1.5, 1.2, 0), width=0.1, height=1.0, depth=0.1) obj2 = SpatialObject( "2", position=Vector3(0, 0, 0), width=0.8, height=1.0, depth=0.6) obj3 = SpatialObject( "3", position=Vector3(0, 0, 1.6), width=0.8, height=0.8, depth=0.8) obj3.angle = .pi/2.0 # initialize reasoner and run pipeline sr = SpatialReasoner() sr.load([obj1, obj2, obj3]) pipeline = "filter(volume > 0.4) | pick(left AND above) | log()" if sr.run(pipeline): # result of processed pipeline as list of SpatialObject result = sr.result() ``` -------------------------------- ### Initialize and Run Spatial Reasoner in Swift Source: https://github.com/metason/spatialreasoner/blob/main/README.md Map 3D entities to SpatialObject instances, load them into the SpatialReasoner, and run a pipeline for inference. The result can be accessed after the pipeline execution. ```swift let obj1 = SpatialObject(id: "1", x:-1.5, y:1.2, z:0, w:0.1, h:1, d:0.1) let obj2 = SpatialObject(id: "2", x:0, y:0, z:0, w:0.8, h:1, d:0.6) let obj3 = SpatialObject(id: "3", x:0, y:0, z:1, w:0.8, h:0.8, d:0.8) obj3.angle = .pi/2.0 // initialize reasoner and run pipeline let sr = SpatialReasoner() sr.load([obj1, obj2, obj3]) let pipeline = "filter(volume > 0.4) | pick(left AND above) | log()" if sr.run(pipeline) { // result of processed pipeline as list of SpatialObject let result = sr.result() ... } ``` -------------------------------- ### Initialize and Run Pipeline in C# Source: https://context7.com/metason/spatialreasoner/llms.txt Initialize the SpatialReasoner, load objects, and run a pipeline. Supports both standard and fluent API calls for pipeline execution. ```csharp // C# - Initialize reasoner and run pipeline var sr = new SpatialReasoner(); SpatialObject[] objs = [lamp, table, chair]; sr.Load(objs); var pipeline = "filter(volume > 0.4) | pick(Left OR Above) | log()"; if (sr.Run(pipeline)) { Console.WriteLine(string.Join('\n', sr.Result)); } // Fluent API alternative SpatialReasoner.Create().Load(objs).Filter("volume>0.4").Pick("Left OR Above").CLog(); ``` -------------------------------- ### Initialize and Run Pipeline in Swift Source: https://context7.com/metason/spatialreasoner/llms.txt Load spatial objects into the SpatialReasoner and execute a pipeline defined by a string. Handles results and loading from JSON. ```swift // Swift - Initialize reasoner and run pipeline let sr = SpatialReasoner() sr.load([lamp, table, chair]) let pipeline = "filter(volume > 0.4) | pick(left AND above) | log()" if sr.run(pipeline) { let result = sr.result() // Returns [SpatialObject] for obj in result { print("Found: \(obj.id) at position (\(obj.x), \(obj.y), \(obj.z))") } } // Load from JSON data let jsonData = """ [ {"id": "wall1", "position": [0, 0, 0], "width": 4.0, "height": 2.5, "depth": 0.1, "type": "wall"}, {"id": "floor", "position": [0, -0.05, 0], "width": 4.0, "height": 0.1, "depth": 4.0, "type": "floor"} ]""".data(using: .utf8)! sr.loadJSON(jsonData) ``` -------------------------------- ### Load and use taxonomies in Swift Source: https://context7.com/metason/spatialreasoner/llms.txt Load taxonomies from URLs or local files to enable isa() checks against class hierarchies. Requires a SpatialReasoner instance. ```swift // Swift - Load and use taxonomies // Load from URL let url = URL(string: "https://service.metason.net/ar/onto/archi.owl")! SpatialTaxonomy.load(from: url) // Load from local file let localURL = Bundle.main.url(forResource: "furniture", withExtension: "owl")! SpatialTaxonomy.load(from: localURL) let sr = SpatialReasoner() sr.load(objects) // Now isa() checks against the loaded taxonomy // If taxonomy has: Furniture -> Seating -> Chair let pipeline = """ isa(Seating) | filter(volume > 0.2) """ // This matches Chair objects because Chair inherits from Seating sr.run(pipeline) ``` -------------------------------- ### Get Nearest Object Source: https://github.com/metason/spatialreasoner/blob/main/README.md Retrieves the single nearest spatial object to the observer by filtering for the observer, picking disjoint objects, sorting by distance, and taking the first result. ```plaintext filter(id == 'observer') | pick(disjoint) | sort(disjoint.delta <) | slice(1) ``` -------------------------------- ### Detect wall-mounted objects in Swift Source: https://context7.com/metason/spatialreasoner/llms.txt Pipeline to identify objects that are mounted on walls and not on the floor. ```swift // Example 3: Detect wall-mounted objects let findWallMounted = """ deduce(connectivity) | select(at ? type == 'wall') | filter(NOT on ? type == 'floor') | map(mounted = 'wall') """ ``` -------------------------------- ### Analyze room layout in Swift Source: https://context7.com/metason/spatialreasoner/llms.txt Pipeline to analyze room layout by identifying objects on the floor, calculating total items and average height, and filtering objects taller than average. ```swift // Example 2: Room layout analysis - find objects on floor grouped by area let analyzeRoom = """ deduce(topology connectivity) | filter(type == 'floor') | pick(on) | calc(totalItems = count(objects); avgHeight = average(objects.height)) | filter(height > data.avgHeight) | sort(volume >) """ ``` -------------------------------- ### Load OWL Taxonomy in Swift Source: https://github.com/metason/spatialreasoner/blob/main/Taxonomy.md This Swift code snippet demonstrates how to load a specific taxonomy in OWL/RDF format from a URL into the Spatial Reasoner library. It then initializes the reasoner and prepares it to run a pipeline. Ensure the URL points to a valid OWL/RDF file. ```swift // load specific taxonomy in OWL/RDF format as XML file let url = URL(string: "https://service.metason.net/ar/onto/test.owl") SpatialTaxonomy.load(from: url) // initialize reasoner and run pipeline let sr = SpatialReasoner() ... ``` -------------------------------- ### Construct spatial scene graph in Swift Source: https://context7.com/metason/spatialreasoner/llms.txt Pipeline to build a spatial scene graph by grouping furniture within rooms and logging the scene structure. ```swift // Example 6: Spatial scene graph construction let buildSceneGraph = """ deduce(topology connectivity) | filter(type == 'wall') | produce(group : type = 'room'; label = 'main_room') | reload() | filter(type == 'furniture') | select(in ? type == 'room') | log(base) | log(3D on in by at) """ let sr = SpatialReasoner() sr.load(sceneObjects) sr.run(buildSceneGraph) let roomContents = sr.result() ``` -------------------------------- ### Adjust Operation Syntax Source: https://github.com/metason/spatialreasoner/blob/main/README.md Configures settings for nearby objects, sectors, and maximum deviation. ```text adjust(max gap 0.05) ``` ```text adjust(sector fixed 1.5) ``` ```text adjust(nearby dimension 2.0) ``` ```text adjust(nearby limit 4.0; max gap 0.1) ``` -------------------------------- ### Create Spatial Objects in Python Source: https://context7.com/metason/spatialreasoner/llms.txt Instantiate SpatialObject instances using the srpy library with position and dimensions. Supports setting rotation angles. ```python # Python - Create spatial objects from srpy import SpatialObject, Vector3 lamp = SpatialObject("lamp", position=Vector3(-1.5, 1.2, 0), width=0.1, height=1.0, depth=0.1) table = SpatialObject("table", position=Vector3(0, 0, 0), width=0.8, height=1.0, depth=0.6) chair = SpatialObject("chair", position=Vector3(0, 0, 1.6), width=0.8, height=0.8, depth=0.8) chair.angle = 3.14159 / 2.0 ``` -------------------------------- ### Load Spatial Taxonomy Source: https://github.com/metason/spatialreasoner/blob/main/README.md Load a domain-specific taxonomy in OWL/RDF format as an XML file before initializing the reasoner. ```swift // load specific taxonomy in OWL/RDF format as XML file let url = URL(string: "https://service.metason.net/ar/onto/test.owl") SpatialTaxonomy.load(from: url) // initialize reasoner and run pipeline let sr = SpatialReasoner() ... ``` -------------------------------- ### Process voice command "show me the chair to my left" in Swift Source: https://context7.com/metason/spatialreasoner/llms.txt Pipeline to interpret a voice command, identifying chairs to the user's left and near them. ```swift // Example 4: Voice command processing - "show me the chair to my left" let voiceQuery = """ deduce(topology visibility) | filter(id == 'ego') | pick(seenleft AND near) | isa(Chair) | slice(1) """ ``` -------------------------------- ### Produce Operation Syntax Source: https://github.com/metason/spatialreasoner/blob/main/README.md Creates new spatial objects based on a contextual specification and attribute assignments. ```text produce(group : type = 'room') ``` ```text produce(by : label = 'corner'; h = 0.02) ``` -------------------------------- ### Log Operation Syntax Source: https://github.com/metason/spatialreasoner/blob/main/README.md Logs the current status of the inference pipeline, with options for base, 3D, and relations. ```text log() ``` ```text log(base) ``` ```text log(3D) ``` ```text log(near right) ``` ```text log(3D near right) ``` -------------------------------- ### Generate Debug Output with log() Source: https://context7.com/metason/spatialreasoner/llms.txt The log() operation generates debug output including markdown reports, 3D scene files, and JSON fact base dumps. Files are saved to the Downloads folder by default. ```swift // Swift - Generate debug output let sr = SpatialReasoner() sr.load(objects) // Basic markdown log with object list, pipeline, and relation graphs let p1 = "filter(type == 'furniture') | log()" // Log specific relations only let p2 = "deduce(topology) | log(near right)" // Export 3D scene file (USDZ for Swift, GLTF for Python/C#) let p3 = "log(3D)" let p4 = "log(3D near right)" // 3D with specific relations highlighted // Export fact base as JSON let p5 = "log(base)" // Array of objects with attributes, variables, and pipeline results // Combined logging let fullDebug = """ deduce(topology connectivity) | filter(type == 'furniture') | pick(near) | sort(near.delta) | log(base) | log(3D) | log(near ontop) """ sr.run(fullDebug) // Generates: // - Markdown file with relation graphs (Mermaid format) // - 3D scene file for visualization // - JSON fact base export ``` -------------------------------- ### Navigate Pipeline Steps with backtrace() and reload() Source: https://context7.com/metason/spatialreasoner/llms.txt Use backtrace() to retrieve objects from previous pipeline steps. reload() reloads all objects, including newly produced ones. Default backtrace is -1. ```swift // Swift - Pipeline navigation operations let sr = SpatialReasoner() sr.load(objects) // Backtrace to previous step output let p1 = "filter(type == 'a') | filter(volume > 0.5) | backtrace(-1)" // Back to before volume filter let p2 = "backtrace(1)" // Same as backtrace(-1) let p3 = "backtrace()" // Default is -1 let p4 = "backtrace(-3)" // Go back 3 steps // Reload all objects including produced ones let createAndUseRoom = """ filter(type == 'wall') | produce(group : type = 'room') | reload() | filter(type == 'furniture') | select(in ? type == 'room') """ // Complex pipeline with backtrace for relation comparison let findRelativePositions = """ deduce(topology) | filter(id == 'reference') | pick(near) | sort(near.delta < -1) """ // The -1 in sort tells it to compare relations to objects 1 step back (the reference) sr.run(createAndUseRoom) ``` -------------------------------- ### Create Spatial Objects in C# Source: https://context7.com/metason/spatialreasoner/llms.txt Instantiate SpatialObject instances with position and dimensions using SCNVector3 for coordinates. Allows setting the rotation angle. ```csharp // C# - Create spatial objects var lamp = new SpatialObject(id: "lamp", position: new SCNVector3(-1.5f, 1.2f, 0), width: 0.1f, height: 1.0f, depth: 0.1f); var table = new SpatialObject(id: "table", position: new SCNVector3(0, 0, 0), width: 0.8f, height: 1.0f, depth: 0.6f); var chair = new SpatialObject(id: "chair", position: new SCNVector3(0, 0, 1.6f), width: 0.8f, height: 0.8f, depth: 0.8f); chair.Angle = (float)(Math.PI / 2.0); ``` -------------------------------- ### Pick Operation Syntax Source: https://github.com/metason/spatialreasoner/blob/main/README.md Selects objects based on their spatial relations. ```text pick(near) ``` ```text pick(ahead AND smaller) ``` ```text pick(near AND (left OR right)) ``` -------------------------------- ### Create Spatial Objects in Swift Source: https://context7.com/metason/spatialreasoner/llms.txt Instantiate SpatialObject instances with position, dimensions, and optional rotation and attributes. Use this for defining 3D entities in Swift. ```swift // Swift - Create spatial objects with position and dimensions let lamp = SpatialObject(id: "lamp", x: -1.5, y: 1.2, z: 0, w: 0.1, h: 1.0, d: 0.1) let table = SpatialObject(id: "table", x: 0, y: 0, z: 0, w: 0.8, h: 1.0, d: 0.6) let chair = SpatialObject(id: "chair", x: 0, y: 0, z: 1.6, w: 0.8, h: 0.8, d: 0.8) // Set rotation angle (yaw in radians, counter-clockwise) chair.angle = .pi / 2.0 // 90 degrees rotation // Set additional attributes table.type = "furniture" table.label = "dining_table" table.existence = "real" // "real" for detected, "virtual" for generated table.visible = true table.confidence.label = 0.85 ``` -------------------------------- ### Calc Operation Syntax Source: https://github.com/metason/spatialreasoner/blob/main/README.md Calculates global variables within the fact base. ```text calc(cnt = count(objects)) ``` ```text calc(maxvol = max(objects.volume); median = median(objects.height)) ``` -------------------------------- ### Adjust Spatial Reasoner Settings Source: https://github.com/metason/spatialreasoner/blob/main/README.md Call `adjust(...)` at the beginning of the inference pipeline to fit settings to the context. Multiple settings are separated by ';'. ```plaintext adjust(max gap 0.02) // set max deviation ``` ```plaintext adjust(max angle 0.1) // set max angle delta ``` ```plaintext adjust(nearby fixed) // set nearby calc schema to .fixed ``` ```plaintext adjust(nearby fixed 1.2) // set nearby calc schema and nearby factor ``` ```plaintext adjust(nearby circle) // set nearby calc schema to .circle ``` ```plaintext adjust(nearby sphere 2) // set nearby calc schema to .sphere ``` ```plaintext adjust(nearby perimeter) // set nearby calc schema to .perimeter ``` ```plaintext adjust(nearby area) // set nearby calc schema to .area ``` ```plaintext adjust(sector fixed 0.5) // set sector calc schema to .fixed ``` ```plaintext adjust(sector dimension) // set nearby calc schema to .dimension ``` ```plaintext adjust(sector perimeter) // set nearby calc schema to .perimeter ``` ```plaintext adjust(sector area 2) // set nearby calc schema to .area ``` ```plaintext adjust(sector nearby) // set nearby calc schema to .nearby ``` ```plaintext adjust(long ratio 4.0) // set long ratio ``` ```plaintext adjust(thin ratio 10.0) // set thin ratio ``` ```plaintext adjust(max gap 0.05; sector dimension; thin ratio 10.0) ``` -------------------------------- ### Produce Operation Source: https://github.com/metason/spatialreasoner/blob/main/README.md Creates new spatial objects or updates existing ones based on a contextual specification. ```APIDOC ## produce() Operation ### Description Create new spatial objects according to a contextual specification and add them to fact base. Optionally change attributes of the new instances. The new `id` is set automatically by concatenating the specification with the `id` of the input object separated with a colon (`spec:id`). When generated objects already exist (identified with their automatically generated `spec:id`), then they will be updated and not created again. Change the `id` in case of enforcing a new object creation. ### Method PRODUCE ### Endpoint N/A (operation within a pipeline) ### Parameters #### Request Body - **specification** (string) - Required - The contextual specification for the new object (e.g., 'on : ...', 'by : ...', 'at : ...', 'copy : ...', 'group : ...', 'sector_type : ...'). The '...' indicates further details or parameters for the specification. ### Request Example ```json { "produce": "on : ..." } ``` ```json { "produce": "by : ..." } ``` ```json { "produce": "at : ..." } ``` ```json { "produce": "copy : ..." } ``` ```json { "produce": "group : ..." } ``` ```json { "produce": "sector_type : ..." } ``` ### Response #### Success Response (200) - **produced_objects** (array) - A list of newly created or updated spatial objects. ``` -------------------------------- ### Aggregate Spatial Objects into a Group Source: https://github.com/metason/spatialreasoner/blob/main/README.md Use the `produce(group:)` rule to aggregate spatial objects into a new group. This is useful for creating container objects, such as a room from walls. ```SpatialReasoning filter(type == 'wall') | produce(group : label = 'room') ``` -------------------------------- ### Select objects with NOT or ALL spatial relations Source: https://github.com/metason/spatialreasoner/blob/main/README.md Extend select() with NOT to exclude specific relations or ALL to ensure a relation holds with every other object. The default is ANY. ```spatialreasoner select(opposite) // = select(ANY opposite) ``` ```spatialreasoner select(NOT opposite) ``` ```spatialreasoner select(ALL opposite) ``` -------------------------------- ### Produce new spatial objects Source: https://github.com/metason/spatialreasoner/blob/main/README.md Use produce() to create new spatial objects based on contextual specifications and optionally update their attributes. New IDs are auto-generated. ```spatialreasoner produce(on : ...) // create object at footprint face ``` ```spatialreasoner produce(by : ...) // create object at touching edge ``` ```spatialreasoner produce(at : ...) // create object at meeting face ``` ```spatialreasoner produce(copy : ...) // create a copy ``` ```spatialreasoner produce(group : ...) // create a group object containing all input objects, aligned with largest input object ``` ```spatialreasoner produce(sector_type : ...) // create object at bbox sector ``` -------------------------------- ### Calculate global variables Source: https://github.com/metason/spatialreasoner/blob/main/README.md Use calc() to compute aggregate values (count, max, median, etc.) across objects and store them as global variables accessible via 'data.' prefix. ```spatialreasoner calc(cnt = count(objects) ``` ```spatialreasoner calc(maxvol = max(objects.volume) ``` ```spatialreasoner calc(median = median(objects.footprint) ``` ```spatialreasoner calc(vol = objects[0].volume; avgh = average(objects.height)) ``` -------------------------------- ### Produce New Objects with produce() in Swift Source: https://context7.com/metason/spatialreasoner/llms.txt Generate new spatial objects using produce() based on contextual specifications. Useful for creating derived objects like groups or copies. ```swift // Swift - Produce new spatial objects let sr = SpatialReasoner() sr.load(objects) // Create a copy of an object let p1 = "filter(id == '1234') | produce(copy : label = 'copy of 1234'; y = 2.0)" // Create a group object containing all input objects (aligned with largest) let p2 = "filter(type == 'wall') | produce(group : label = 'room')" // Create objects at connectivity positions let p3 = "filter(type == 'wall') | produce(by : label = 'corner'; h = 0.02)" // At touching edges // Other produce specifications: // produce(on : ...) - create at footprint face // produce(at : ...) - create at meeting face // produce(sector_type : ...) - create at specific bbox sector // Room creation example let createRoom = """ deduce(connectivity) | filter(type == 'wall') | produce(group : type = 'room'; label = 'living room') """ // Corner detection let findCorners = """ deduce(connectivity) | filter(type == 'wall') | produce(by : label = 'corner'; type = 'corner'; h = 0.02; w = 0.02; d = 0.02) | reload() | filter(type == 'corner') """ sr.run(findCorners) let corners = sr.result() ``` -------------------------------- ### Backtrace Operation Syntax Source: https://github.com/metason/spatialreasoner/blob/main/README.md Outputs spatial objects from a specified number of steps back in the inference pipeline. ```text backtrace(-2) ``` -------------------------------- ### Select Operation Syntax Source: https://github.com/metason/spatialreasoner/blob/main/README.md Selects objects based on spatial relations, optionally combined with attribute conditions. ```text select(opposite) ``` ```text select(ontop ? id == 'table1') ``` ```text select(on ? type == 'floor') ``` ```text select(ahead AND smaller ? footprint < 0.5) ``` -------------------------------- ### Backtrace in the inference pipeline Source: https://github.com/metason/spatialreasoner/blob/main/README.md Use backtrace() to retrieve spatial objects from previous steps in the inference pipeline. Default is one step back. ```spatialreasoner backtrace(-1) // backtrace one step ``` ```spatialreasoner backtrace(1) // same as backtrace(-1) ``` ```spatialreasoner backtrace() // same as backtrace(-1), default value is -1 ``` ```spatialreasoner backtrace(-3) // goes back 3 steps to take input as its output ``` -------------------------------- ### Map Operation Syntax Source: https://github.com/metason/spatialreasoner/blob/main/README.md Calculates values for object attributes. ```text map(weight = volume * 140.0) ``` ```text map(type = 'double bed') ``` -------------------------------- ### Select Operation Source: https://github.com/metason/spatialreasoner/blob/main/README.md Selects objects based on spatial relations and optional attribute conditions. Analogous to SQL SELECT. ```APIDOC ## select() Operation ### Description Select objects that have spatial relations with other objects using the `select(`_relation ? attribute conditions_`)` operation. Attribute conditions are optional and will filter the referenced object. You can read the select() operation analog to a SQL-SELECT as "SELECT object WHERE ...". It can be read as "SELECT spatial objects WHERE spatial relation exists with other spatial objects [that fulfill the attribute conditions]". With the NOT statement, the select() operator selects only spatial objects without the specified spatial relation. With the ALL statement, the select() operator selects only spatial objects that have the specified spatial relationship with all other objects. If NOT or ALL is missing, it is interpreted as ANY (can but does not have to be specified). ### Method SELECT (conceptual) ### Endpoint N/A (operation within a pipeline) ### Parameters #### Query Parameters - **relation** (string) - Required - The spatial relation to check (e.g., 'opposite', 'ontop', 'on', 'ahead'). - **attribute conditions** (string) - Optional - Conditions to filter the referenced object (e.g., "label == 'table'", "type == 'floor'", "footprint < 0.5"). - **modifier** (string) - Optional - 'NOT' or 'ALL'. Defaults to 'ANY' if not specified. ### Request Example ``` select(opposite) select(ontop ? label == 'table') select(on ? type == 'floor') select(ahead AND smaller ? footprint < 0.5) select(NOT opposite) select(ALL opposite) ``` ### Response #### Success Response (200) - **selected_objects** (array) - A list of spatial objects that satisfy the conditions. ``` -------------------------------- ### Pick by Spatial Relations Source: https://github.com/metason/spatialreasoner/blob/main/README.md Select spatial objects based on their spatial relationships, such as being 'near' or in a specific direction relative to another object. ```plaintext pick(near AND (left OR behind)) ``` -------------------------------- ### Select Objects by Spatial Relations with pick() Source: https://context7.com/metason/spatialreasoner/llms.txt Use pick() to select objects based on their spatial relations to the current set. Relations can be combined with boolean operators AND, OR, and NOT. Refer to the documentation for a full list of available spatial relation predicates. ```swift // Swift - Pick objects by spatial relations let sr = SpatialReasoner() sr.load(objects) // Single relation let p1 = "filter(id == 'table') | pick(near)" // Objects near the table // Combined relations let p2 = "filter(id == 'ego') | pick(ahead AND left)" // Ahead-left from observer let p3 = "pick(near AND (left OR right))" // Near and to either side let p4 = "pick(ontop AND NOT moving)" // On top and stationary // Spatial relation predicates available: // Proximity: near, far // Directionality: left, right, ahead, behind, above, below // Adjacency: leftside, rightside, frontside, backside, beside, upperside, lowerside, ontop, beneath // Orientation: aligned, orthogonal, opposite, frontaligned, backaligned, leftaligned, rightaligned // Assembly: disjoint, inside, containing, overlapping, crossing, touching, meeting // Connectivity: on, in, by, at // Visibility: seenleft, seenright, infront, atrear, elevenoclock, twooclock, etc. // Comparability: bigger, smaller, longer, shorter, taller, thinner, wider // Similarity: samewidth, sameheight, samevolume, congruent, etc. let pipeline = "deduce(topology) | filter(id == 'observer') | pick(disjoint AND near) | filter(type == 'furniture')" sr.run(pipeline) ``` -------------------------------- ### pick() Operation Source: https://github.com/metason/spatialreasoner/blob/main/README.md Picks objects along their spatial relations with the pick(_relation conditions_) operation. ```APIDOC ## pick() Operation ### Description Picks objects along their spatial relations with the `pick(`_relation conditions_`)` operation. ### Method Not specified (function call syntax used) ### Endpoint Not applicable (function call) ### Parameters - `relation_conditions` (string) - Conditions specifying the spatial relations to pick objects by. Can include relation keywords and boolean compounds. ### Request Example ``` pick(near) pick(ahead AND smaller) pick(near AND (left OR right)) ``` ### Response No specific response format is detailed, as this is an operation call within a pipeline. ``` -------------------------------- ### adjust() Operation Source: https://github.com/metason/spatialreasoner/blob/main/README.md Adjusts settings of the spatial reasoner to fit the actual context, environment, and dominant object size. Call adjust(...) at the beginning of the inference pipeline. Multiple settings within an adjust(...) call are separated by ';'. ```APIDOC ## adjust() Operation ### Description Adjusts settings of the spatial reasoner to fit the actual context, environment, and dominant object size. Call `adjust(...)` at the beginning of the inference pipeline. By setting a calculation schema, the corresponding factor value can optionally be specified as well. Multiple settings within an `adjust(...)` call are separated by `;`. ### Method Not specified (function call syntax used) ### Endpoint Not applicable (function call) ### Parameters Parameters are specified as key-value pairs or simply by key within the function call. Examples include: - `max gap` (float) - Sets the maximum deviation. - `max angle` (float) - Sets the maximum angle delta. - `nearby` (string) - Sets the nearby calculation schema (e.g., `fixed`, `circle`, `sphere`, `perimeter`, `area`, `dimension`, `sector`, `nearby`). Optionally followed by a factor (float). - `sector` (string) - Sets the sector calculation schema (e.g., `fixed`, `dimension`, `perimeter`, `area`, `nearby`). Optionally followed by a factor (float). - `long ratio` (float) - Sets the long ratio. - `thin ratio` (float) - Sets the thin ratio. ### Request Example ``` adjust(max gap 0.02) adjust(nearby fixed 1.2) adjust(max gap 0.05; sector dimension; thin ratio 10.0) ``` ### Response No specific response format is detailed, as this is an operation call within a pipeline. ``` -------------------------------- ### Calc Operation Source: https://github.com/metason/spatialreasoner/blob/main/README.md Calculates global variables in the fact base using various aggregation functions. ```APIDOC ## calc() Operation ### Description Calculate global variables in fact base with the `calc(`_variable assignments_`)` operation. The calculated variables are accessible as `data.`_key_, e.g., in `filter(height > data.avgh)`. Available function calls: `average(), sum(), count(), median(), mode(), stddev(), min(), max()`. ### Method CALC ### Endpoint N/A (operation within a pipeline) ### Parameters #### Request Body - **variable assignments** (string) - Required - Assignments of variables using aggregation functions (e.g., 'cnt = count(objects)', 'maxvol = max(objects.volume)', 'vol = objects[0].volume; avgh = average(objects.height)'). ### Request Example ```json { "calc": "cnt = count(objects)" } ``` ```json { "calc": "maxvol = max(objects.volume)" } ``` ```json { "calc": "vol = objects[0].volume; avgh = average(objects.height)" } ``` ### Response #### Success Response (200) - **calculated_variables** (object) - An object containing the newly calculated global variables. ``` -------------------------------- ### Select objects based on spatial relations Source: https://github.com/metason/spatialreasoner/blob/main/README.md Use select() to filter objects based on spatial relationships with other objects. Attribute conditions can further refine the selection. ```spatialreasoner select(opposite) ``` ```spatialreasoner select(ontop ? label == 'table') ``` ```spatialreasoner select(on ? type == 'floor') ``` ```spatialreasoner select(ahead AND smaller ? footprint < 0.5) ``` -------------------------------- ### Map Operation Source: https://github.com/metason/spatialreasoner/blob/main/README.md Sets or calculates values of local object attributes. ```APIDOC ## map() Operation ### Description Set or calculate values of local object attributes with the `map(`_attribute assignments_`)` operation. ### Method MAP ### Endpoint N/A (operation within a pipeline) ### Parameters #### Request Body - **attribute assignments** (string) - Required - Assignments for local object attributes (e.g., 'shape = "cylindrical"', 'type = "bed"', 'weight = volume * 140.0'). ### Request Example ```json { "map": "shape = 'cylindrical'" } ``` ```json { "map": "type = 'bed'" } ``` ```json { "map": "weight = volume * 140.0" } ``` ### Response #### Success Response (200) - **updated_objects** (array) - A list of spatial objects with updated attributes. ``` -------------------------------- ### Sort by Attributes Operation Syntax Source: https://github.com/metason/spatialreasoner/blob/main/README.md Sorts objects by specified object attributes, with an optional comparator. ```text sort(length) ``` ```text sort(volume) ``` ```text sort(width <) ``` ```text sort(width >) ``` -------------------------------- ### Filter Objects by Relation and Attribute Conditions with select() Source: https://context7.com/metason/spatialreasoner/llms.txt Use select() to filter objects based on spatial relations to other objects that meet optional attribute conditions. Supports ANY (default), NOT, and ALL quantifiers for relation matching. ```swift // Swift - Select with relation and attribute conditions let sr = SpatialReasoner() sr.load(objects) // Select objects with relation to any matching object let p1 = "select(opposite)" // Objects with any opposite relation let p2 = "select(ontop ? label == 'table')" // Objects on top of tables let p3 = "select(on ? type == 'floor')" // Objects on the floor let p4 = "select(ahead AND smaller ? footprint < 0.5)" // Ahead and smaller than small objects // Use NOT to select objects WITHOUT the relation let p5 = "select(NOT opposite)" // Objects with no opposite relations let p6 = "select(NOT on ? type == 'floor')" // Objects NOT on the floor (floating/wall-mounted) // Use ALL to require relation with ALL matching objects let p7 = "select(ALL opposite)" // Must be opposite to all other objects // Complex selection pipeline let pipeline = """ deduce(topology connectivity) | filter(type == 'furniture') | select(beside ? type == 'wall') | sort(volume) | slice(1..3) """ sr.run(pipeline) ``` -------------------------------- ### Sort objects by metric attributes Source: https://github.com/metason/spatialreasoner/blob/main/README.md Use sort() with a metric attribute to order objects. Specify '<' for ascending or '>' for descending order. ```spatialreasoner sort(length) ``` ```spatialreasoner sort(volume) ``` ```spatialreasoner sort(width <) // ascending ``` ```spatialreasoner sort(width >) // descending ```