Newer
Older
HoloAnatomy / Assets / HoloToolkit / SpatialUnderstanding / Scripts / SpatialUnderstandingDllObjectPlacement.cs
SURFACEBOOK2\jackwynne on 25 May 2018 25 KB v1
  1. // Copyright (c) Microsoft Corporation. All rights reserved.
  2. // Licensed under the MIT License. See LICENSE in the project root for license information.
  3.  
  4. using UnityEngine;
  5. using System.Collections;
  6. using System.Runtime.InteropServices;
  7. using System;
  8. using System.Collections.Generic;
  9.  
  10. namespace HoloToolkit.Unity
  11. {
  12. /// <summary>
  13. /// Encapsulates the object placement queries of the understanding DLL.
  14. /// These queries will not be valid until after scanning is finalized.
  15. /// </summary>
  16. public static class SpatialUnderstandingDllObjectPlacement
  17. {
  18. /// <summary>
  19. /// Defines an object placement query. A query consists of
  20. /// a type a name, type, set of rules, and set of constraints.
  21. ///
  22. /// Rules may not be violated by the returned query. Possible
  23. /// locations that satisfy the type and rules are selected
  24. /// by optimizing within the constraint list.
  25. /// </summary>
  26. [StructLayout(LayoutKind.Sequential, Pack = 1)]
  27. public struct ObjectPlacementDefinition
  28. {
  29. /// <summary>
  30. /// Type of object placement. Each type has a custom set
  31. /// of parameter.
  32. /// </summary>
  33. public enum PlacementType
  34. {
  35. Place_OnFloor,
  36. Place_OnWall,
  37. Place_OnCeiling,
  38. Place_OnShape,
  39. Place_OnEdge,
  40. Place_OnFloorAndCeiling,
  41. Place_RandomInAir,
  42. Place_InMidAir,
  43. Place_UnderPlatformEdge,
  44. };
  45.  
  46. /// <summary>
  47. /// Type of wall.
  48. /// External walls bound the playspace. Virtual walls are created
  49. /// at the edge of the playspace when an external wall does not
  50. /// exist.
  51. /// </summary>
  52. [FlagsAttribute]
  53. public enum WallTypeFlags
  54. {
  55. None = 0,
  56. Normal = (1 << 0),
  57. External = (1 << 1),
  58. Virtual = (1 << 2),
  59. ExternalVirtual = (1 << 3),
  60. };
  61.  
  62. /// <summary>
  63. /// Constructs an object placement query definition requiring the object to
  64. /// be placed on the floor.
  65. /// </summary>
  66. /// <param name="halfDims">Required half size of the requested bounding volume</param>
  67. /// <returns>Constructed object placement definition</returns>
  68. public static ObjectPlacementDefinition Create_OnFloor(Vector3 halfDims)
  69. {
  70. ObjectPlacementDefinition placement = new ObjectPlacementDefinition();
  71. placement.Type = PlacementType.Place_OnFloor;
  72. placement.HalfDims = halfDims;
  73. return placement;
  74. }
  75.  
  76. /// <summary>
  77. /// Constructs an object placement query definition requiring the object to
  78. /// be placed on a wall.
  79. /// </summary>
  80. /// <param name="halfDims">Required half size of the requested bounding volume</param>
  81. /// <param name="heightMin">Minimum height of the requested volume above the floor</param>
  82. /// <param name="heightMax">Maximum height of the requested volume above the floor</param>
  83. /// <param name="wallTypes">Bit mask of possible walls to consider, defined by WallTypeFlags</param>
  84. /// <param name="marginLeft">Required empty wall space to the left of the volume, as defined by facing the wall</param>
  85. /// <param name="marginRight">Required empty wall space to the right of the volume, as defined by facing the wall</param>
  86. /// <returns>Constructed object placement definition</returns>
  87. public static ObjectPlacementDefinition Create_OnWall(
  88. Vector3 halfDims,
  89. float heightMin,
  90. float heightMax,
  91. WallTypeFlags wallTypes = WallTypeFlags.External | WallTypeFlags.Normal,
  92. float marginLeft = 0.0f,
  93. float marginRight = 0.0f)
  94. {
  95. ObjectPlacementDefinition placement = new ObjectPlacementDefinition();
  96. placement.Type = PlacementType.Place_OnWall;
  97. placement.HalfDims = halfDims;
  98. placement.PlacementParam_Float_0 = heightMin;
  99. placement.PlacementParam_Float_1 = heightMax;
  100. placement.PlacementParam_Float_2 = marginLeft;
  101. placement.PlacementParam_Float_3 = marginRight;
  102. placement.WallFlags = (int)wallTypes;
  103. return placement;
  104. }
  105.  
  106. /// <summary>
  107. /// Constructs an object placement query definition requiring the object to
  108. /// be place on the ceiling.
  109. /// </summary>
  110. /// <param name="halfDims">Required half size of the requested bounding volume</param>
  111. /// <returns>Constructed object placement definition</returns>
  112. public static ObjectPlacementDefinition Create_OnCeiling(Vector3 halfDims)
  113. {
  114. ObjectPlacementDefinition placement = new ObjectPlacementDefinition();
  115. placement.Type = PlacementType.Place_OnCeiling;
  116. placement.HalfDims = halfDims;
  117. return placement;
  118. }
  119.  
  120. /// <summary>
  121. /// Constructs an object placement query definition requiring the object to
  122. /// be placed on top of another object placed object.
  123. /// </summary>
  124. /// <param name="halfDims">Required half size of the requested bounding volume</param>
  125. /// <param name="shapeName">Name of the placed object</param>
  126. /// <param name="componentIndex">Index of the component within shapeName</param>
  127. /// <returns>Constructed object placement definition</returns>
  128. public static ObjectPlacementDefinition Create_OnShape(Vector3 halfDims, string shapeName, int componentIndex)
  129. {
  130. ObjectPlacementDefinition placement = new ObjectPlacementDefinition();
  131. placement.Type = PlacementType.Place_OnShape;
  132. placement.HalfDims = halfDims;
  133. placement.PlacementParam_Str_0 = SpatialUnderstanding.Instance.UnderstandingDLL.PinString(shapeName);
  134. placement.PlacementParam_Int_0 = componentIndex;
  135. return placement;
  136. }
  137.  
  138. /// <summary>
  139. /// Constructs an object placement query definition requiring the object to
  140. /// be placed on the edge of a platform.
  141. /// </summary>
  142. /// <param name="halfDims">Required half size of the requested bounding volume</param>
  143. /// <param name="halfDimsBottom">Half size of the bottom part of the placement volume</param>
  144. /// <returns>Constructed object placement definition</returns>
  145. public static ObjectPlacementDefinition Create_OnEdge(Vector3 halfDims, Vector3 halfDimsBottom)
  146. {
  147. ObjectPlacementDefinition placement = new ObjectPlacementDefinition();
  148. placement.Type = PlacementType.Place_OnEdge;
  149. placement.HalfDims = halfDims;
  150. placement.PlacementParam_Float_0 = halfDimsBottom.x;
  151. placement.PlacementParam_Float_1 = halfDimsBottom.y;
  152. placement.PlacementParam_Float_2 = halfDimsBottom.z;
  153. return placement;
  154. }
  155.  
  156. /// <summary>
  157. /// Constructs an object placement query definition requiring the object to
  158. /// be have space on the floor and ceiling within the same vertical space.
  159. /// </summary>
  160. /// <param name="halfDims">Required half size of the requested bounding volume</param>
  161. /// <param name="halfDimsBottom">Half size of the bottom part of the placement volume</param>
  162. /// <returns>Constructed object placement definition</returns>
  163. public static ObjectPlacementDefinition Create_OnFloorAndCeiling(Vector3 halfDims, Vector3 halfDimsBottom)
  164. {
  165. ObjectPlacementDefinition placement = new ObjectPlacementDefinition();
  166. placement.Type = PlacementType.Place_OnFloorAndCeiling;
  167. placement.HalfDims = halfDims;
  168. placement.PlacementParam_Float_0 = halfDimsBottom.x;
  169. placement.PlacementParam_Float_1 = halfDimsBottom.y;
  170. placement.PlacementParam_Float_2 = halfDimsBottom.z;
  171. return placement;
  172. }
  173.  
  174. /// <summary>
  175. /// Constructs an object placement query definition requiring the object to
  176. /// be placed floating in space, within the playspace. Spaces visible from the
  177. /// center of the playspace are favored.
  178. /// </summary>
  179. /// <param name="halfDims">Required half size of the requested bounding volume</param>
  180. /// <returns>Constructed object placement definition</returns>
  181. public static ObjectPlacementDefinition Create_RandomInAir(Vector3 halfDims)
  182. {
  183. ObjectPlacementDefinition placement = new ObjectPlacementDefinition();
  184. placement.Type = PlacementType.Place_RandomInAir;
  185. placement.HalfDims = halfDims;
  186. return placement;
  187. }
  188.  
  189. /// <summary>
  190. /// Constructs an object placement query definition requiring the object to
  191. /// be placed floating in space, within the playspace. This query requires that
  192. /// other objects do not collide with the placement volume.
  193. /// </summary>
  194. /// <param name="halfDims">Required half size of the requested bounding volume</param>
  195. /// <returns>Constructed object placement definition</returns>
  196. public static ObjectPlacementDefinition Create_InMidAir(Vector3 halfDims)
  197. {
  198. ObjectPlacementDefinition placement = new ObjectPlacementDefinition();
  199. placement.Type = PlacementType.Place_InMidAir;
  200. placement.HalfDims = halfDims;
  201. return placement;
  202. }
  203.  
  204. /// <summary>
  205. /// Constructs an object placement query definition requiring the object to
  206. /// be place under a platform edge.
  207. /// </summary>
  208. /// <param name="halfDims">Required half size of the requested bounding volume</param>
  209. /// <returns>Constructed object placement definition</returns>
  210. public static ObjectPlacementDefinition Create_UnderPlatformEdge(Vector3 halfDims)
  211. {
  212. ObjectPlacementDefinition placement = new ObjectPlacementDefinition();
  213. placement.Type = PlacementType.Place_UnderPlatformEdge;
  214. placement.HalfDims = halfDims;
  215. return placement;
  216. }
  217.  
  218. public PlacementType Type;
  219. public int PlacementParam_Int_0;
  220. public float PlacementParam_Float_0;
  221. public float PlacementParam_Float_1;
  222. public float PlacementParam_Float_2;
  223. public float PlacementParam_Float_3;
  224. public IntPtr PlacementParam_Str_0;
  225. public int WallFlags;
  226. public Vector3 HalfDims;
  227. };
  228.  
  229. /// <summary>
  230. /// Defines an object placement rule. Rules are one part of an object
  231. /// placement definition. Rules may not be violated by the returned query.
  232. /// </summary>
  233. [StructLayout(LayoutKind.Sequential, Pack = 1)]
  234. public struct ObjectPlacementRule
  235. {
  236. /// <summary>
  237. /// Type of object placement rule. Each rule is defined by its
  238. /// type and a set of per-type parameters. The supplied static
  239. /// construction functions may be used to create rules.
  240. /// </summary>
  241. public enum ObjectPlacementRuleType
  242. {
  243. Rule_AwayFromPosition,
  244. Rule_AwayFromWalls,
  245. Rule_AwayFromOtherObjects,
  246. };
  247.  
  248. /// <summary>
  249. /// Constructs an object placement rule requiring the placement volume to
  250. /// be placed a minimum distance away from the specified position.
  251. /// </summary>
  252. /// <param name="position">Defines the center position for the center of the invalid placement space.</param>
  253. /// <param name="minDistance">Defines the radius of the invalid placement space.</param>
  254. /// <returns>Constructed object placement rule</returns>
  255. public static ObjectPlacementRule Create_AwayFromPosition(Vector3 position, float minDistance)
  256. {
  257. ObjectPlacementRule rule = new ObjectPlacementRule();
  258. rule.Type = ObjectPlacementRuleType.Rule_AwayFromPosition;
  259. rule.RuleParam_Vec3_0 = position;
  260. rule.RuleParam_Float_0 = minDistance;
  261. return rule;
  262. }
  263.  
  264. /// <summary>
  265. /// Constructs an object placement rule requiring the placement volume to
  266. /// be placed a minimum distance away from any wall
  267. /// </summary>
  268. /// <param name="minDistance">Minimum distance from a wall</param>
  269. /// <param name="minWallHeight">Minimum height of a wall to be considered by this rule</param>
  270. /// <returns>Constructed object placement rule</returns>
  271. public static ObjectPlacementRule Create_AwayFromWalls(float minDistance, float minWallHeight = 0.0f)
  272. {
  273. ObjectPlacementRule rule = new ObjectPlacementRule();
  274. rule.Type = ObjectPlacementRuleType.Rule_AwayFromWalls;
  275. rule.RuleParam_Float_0 = minDistance;
  276. rule.RuleParam_Float_1 = minWallHeight;
  277. return rule;
  278. }
  279.  
  280. /// <summary>
  281. /// Constructs an object placement rule requiring the placement volume to
  282. /// be placed a minimum distance away from other placed objects
  283. /// </summary>
  284. /// <param name="minDistance">Minimum distance from other placed objects</param>
  285. /// <returns>Constructed object placement rule</returns>
  286. public static ObjectPlacementRule Create_AwayFromOtherObjects(float minDistance)
  287. {
  288. ObjectPlacementRule rule = new ObjectPlacementRule();
  289. rule.Type = ObjectPlacementRuleType.Rule_AwayFromOtherObjects;
  290. rule.RuleParam_Float_0 = minDistance;
  291. return rule;
  292. }
  293.  
  294. public ObjectPlacementRuleType Type;
  295. public int RuleParam_Int_0;
  296. public float RuleParam_Float_0;
  297. public float RuleParam_Float_1;
  298. public Vector3 RuleParam_Vec3_0;
  299. };
  300.  
  301. /// <summary>
  302. /// Defines an object placement constraint. Constraints are one part of an object
  303. /// placement definition. Possible object placement locations are picked by the
  304. /// location that minimally violates the set of constraints.
  305. /// </summary>
  306. [StructLayout(LayoutKind.Sequential, Pack = 1)]
  307. public struct ObjectPlacementConstraint
  308. {
  309. /// <summary>
  310. /// Types of object placement constraints
  311. /// </summary>
  312. public enum ObjectPlacementConstraintType
  313. {
  314. Constraint_NearPoint,
  315. Constraint_NearWall,
  316. Constraint_AwayFromWalls,
  317. Constraint_NearCenter,
  318. Constraint_AwayFromOtherObjects,
  319. Constraint_AwayFromPoint
  320. };
  321.  
  322. /// <summary>
  323. /// Constructs an object placement constraint requesting that the placement volume
  324. /// be placed no closer than minDistance and no further than maxDistance from
  325. /// the specified position.
  326. /// </summary>
  327. /// <param name="position">The center point from switch minDistance and maxDistance define their volumes</param>
  328. /// <param name="minDistance">The minimum distance from position to place the object</param>
  329. /// <param name="maxDistance">The maximum distance from position to place the object</param>
  330. /// <returns>Constructed object placement constraint</returns>
  331. public static ObjectPlacementConstraint Create_NearPoint(Vector3 position, float minDistance = 0.0f, float maxDistance = 0.0f)
  332. {
  333. ObjectPlacementConstraint constraint = new ObjectPlacementConstraint();
  334. constraint.Type = ObjectPlacementConstraintType.Constraint_NearPoint;
  335. constraint.RuleParam_Vec3_0 = position;
  336. constraint.RuleParam_Float_0 = minDistance;
  337. constraint.RuleParam_Float_1 = maxDistance;
  338. return constraint;
  339. }
  340.  
  341. /// <summary>
  342. /// Constructs an object placement constraint requesting that the placement volume
  343. /// be placed no closer than minDistance and no further than maxDistance from
  344. /// a wall.
  345. /// </summary>
  346. /// <param name="minDistance">The minimum distance from position to place the object</param>
  347. /// <param name="maxDistance">The maximum distance from position to place the object</param>
  348. /// <param name="minWallHeight">Minimum height of a wall to be considered by this rule</param>
  349. /// <param name="includeVirtualWalls">Indicates virtual walls should be considered in this query</param>
  350. /// <returns>Constructed object placement constraint</returns>
  351. public static ObjectPlacementConstraint Create_NearWall(float minDistance = 0.0f, float maxDistance = 0.0f, float minWallHeight = 0.0f, bool includeVirtualWalls = false)
  352. {
  353. ObjectPlacementConstraint constraint = new ObjectPlacementConstraint();
  354. constraint.Type = ObjectPlacementConstraintType.Constraint_NearWall;
  355. constraint.RuleParam_Float_0 = minDistance;
  356. constraint.RuleParam_Float_1 = maxDistance;
  357. constraint.RuleParam_Float_2 = minWallHeight;
  358. constraint.RuleParam_Int_0 = includeVirtualWalls ? 1 : 0;
  359. return constraint;
  360. }
  361.  
  362. /// <summary>
  363. /// Constructs an object placement constraint requesting that the placement volume
  364. /// be placed away from all walls.
  365. /// </summary>
  366. /// <returns>Constructed object placement constraint</returns>
  367. public static ObjectPlacementConstraint Create_AwayFromWalls()
  368. {
  369. ObjectPlacementConstraint constraint = new ObjectPlacementConstraint();
  370. constraint.Type = ObjectPlacementConstraintType.Constraint_AwayFromWalls;
  371. return constraint;
  372. }
  373.  
  374. /// <summary>
  375. /// Constructs an object placement constraint requesting that the placement volume
  376. /// be placed near the center of the playspace.
  377. /// </summary>
  378. /// <param name="minDistance">The minimum distance from the center to place the object</param>
  379. /// <param name="maxDistance">The maximum distance from the center to place the object</param>
  380. /// <returns>Constructed object placement constraint</returns>
  381. public static ObjectPlacementConstraint Create_NearCenter(float minDistance = 0.0f, float maxDistance = 0.0f)
  382. {
  383. ObjectPlacementConstraint constraint = new ObjectPlacementConstraint();
  384. constraint.Type = ObjectPlacementConstraintType.Constraint_NearCenter;
  385. constraint.RuleParam_Float_0 = minDistance;
  386. constraint.RuleParam_Float_1 = maxDistance;
  387. return constraint;
  388. }
  389.  
  390. /// <summary>
  391. /// Constructs an object placement constraint requesting that the placement volume
  392. /// be placed away from other place objects.
  393. /// </summary>
  394. /// <returns>Constructed object placement constraint</returns>
  395. public static ObjectPlacementConstraint Create_AwayFromOtherObjects()
  396. {
  397. ObjectPlacementConstraint constraint = new ObjectPlacementConstraint();
  398. constraint.Type = ObjectPlacementConstraintType.Constraint_AwayFromOtherObjects;
  399. return constraint;
  400. }
  401.  
  402. /// <summary>
  403. /// Constructs an object placement constraint requesting that the placement volume
  404. /// be placed away from the specified position.
  405. /// </summary>
  406. /// <param name="position">The center point from switch minDistance and maxDistance define their volumes</param>
  407. /// <returns>Constructed object placement constraint</returns>
  408. public static ObjectPlacementConstraint Create_AwayFromPoint(Vector3 position)
  409. {
  410. ObjectPlacementConstraint constraint = new ObjectPlacementConstraint();
  411. constraint.Type = ObjectPlacementConstraintType.Constraint_AwayFromPoint;
  412. constraint.RuleParam_Vec3_0 = position;
  413. return constraint;
  414. }
  415.  
  416. public ObjectPlacementConstraintType Type;
  417. public int RuleParam_Int_0;
  418. public float RuleParam_Float_0;
  419. public float RuleParam_Float_1;
  420. public float RuleParam_Float_2;
  421. public Vector3 RuleParam_Vec3_0;
  422. };
  423.  
  424. /// <summary>
  425. /// Object placement result. Defines an oriented bounding box result for the
  426. /// object placement query.
  427. /// </summary>
  428. [StructLayout(LayoutKind.Sequential, Pack = 1)]
  429. public class ObjectPlacementResult : ICloneable
  430. {
  431. public object Clone()
  432. {
  433. return this.MemberwiseClone();
  434. }
  435.  
  436. public Vector3 Position;
  437. public Vector3 HalfDims;
  438. public Vector3 Forward;
  439. public Vector3 Right;
  440. public Vector3 Up;
  441. };
  442.  
  443. // Functions
  444. /// <summary>
  445. /// Initialized the object placement solver. This should be called after the
  446. /// scanning phase has finish and the playspace has been finalized.
  447. /// </summary>
  448. /// <returns></returns>
  449. [DllImport("SpatialUnderstanding", CallingConvention = CallingConvention.Cdecl)]
  450. public static extern int Solver_Init();
  451.  
  452. /// <summary>
  453. /// Executes an object placement query.
  454. ///
  455. /// A query consists of a type a name, type, set of rules,
  456. /// and set of constraints.
  457. ///
  458. /// Rules may not be violated by the returned query. Possible
  459. /// locations that satisfy the type and rules are selected
  460. /// by optimizing within the constraint list.
  461. ///
  462. /// Objects placed with Solver_PlaceObject persist until removed
  463. /// and are considered in subsequent queries by some rules and constraints.
  464. /// </summary>
  465. /// <param name="objectName">Name of the object placement query</param>
  466. /// <param name="placementDefinition">The placement definition, of type ObjectPlacementDefinition</param>
  467. /// <param name="placementRuleCount">Length of the provided placementRules array</param>
  468. /// <param name="placementRules">Array of ObjectPlacementRule structures, defining the rules</param>
  469. /// <param name="constraintCount">Length of the provided placementConstraints array</param>
  470. /// <param name="placementConstraints">Array of ObjectPlacementConstraint structures, defining the constraints</param>
  471. /// <param name="placementResult">Pointer to an ObjectPlacementResult structure to receive the result of the query </param>
  472. /// <returns>Zero on failure, one on success</returns>
  473. [DllImport("SpatialUnderstanding", CallingConvention = CallingConvention.Cdecl)]
  474. public static extern int Solver_PlaceObject(
  475. [In, MarshalAs(UnmanagedType.LPStr)] string objectName,
  476. [In] IntPtr placementDefinition,// ObjectPlacementDefinition
  477. [In] int placementRuleCount,
  478. [In] IntPtr placementRules, // ObjectPlacementRule
  479. [In] int constraintCount,
  480. [In] IntPtr placementConstraints,// ObjectPlacementConstraint
  481. [Out] IntPtr placementResult); // ObjectPlacementResult
  482.  
  483. /// <summary>
  484. /// Removed a solved object.
  485. ///
  486. /// Objects placed with Solver_PlaceObject persist until removed
  487. /// and are considered in subsequent queries by some rules and constraints.
  488. /// </summary>
  489. /// <param name="objectName"></param>
  490. /// <returns></returns>
  491. [DllImport("SpatialUnderstanding", CallingConvention = CallingConvention.Cdecl)]
  492. public static extern int Solver_RemoveObject(
  493. [In, MarshalAs(UnmanagedType.LPStr)] string objectName);
  494.  
  495. /// <summary>
  496. /// Removed all solved object placements.
  497. ///
  498. /// Objects placed with Solver_PlaceObject persist until removed
  499. /// and are considered in subsequent queries by some rules and constraints.
  500. /// </summary>
  501. [DllImport("SpatialUnderstanding", CallingConvention = CallingConvention.Cdecl)]
  502. public static extern void Solver_RemoveAllObjects();
  503. }
  504. }