Point Cloud Library (PCL)  1.9.1-dev
opennurbs_instance.h
1 /* $NoKeywords: $ */
2 /*
3 //
4 // Copyright (c) 1993-2012 Robert McNeel & Associates. All rights reserved.
5 // OpenNURBS, Rhinoceros, and Rhino3D are registered trademarks of Robert
6 // McNeel & Associates.
7 //
8 // THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY.
9 // ALL IMPLIED WARRANTIES OF FITNESS FOR ANY PARTICULAR PURPOSE AND OF
10 // MERCHANTABILITY ARE HEREBY DISCLAIMED.
11 //
12 // For complete openNURBS copyright information see <http://www.opennurbs.org>.
13 //
14 ////////////////////////////////////////////////////////////////
15 */
16 
17 #if !defined(OPENNURBS_INSTANCE_INC_)
18 #define OPENNURBS_INSTANCE_INC_
19 
20 /*
21 Description:
22  An ON_InstanceDefinition defines the geometry used by
23  instance references.
24 See Also:
25  ON_InstanceRef
26 */
27 class ON_CLASS ON_InstanceDefinition : public ON_Geometry
28 {
29  ON_OBJECT_DECLARE(ON_InstanceDefinition);
30 
31 public:
32 
33  // IDEF_UPDATE_TYPE lists the possible relationships between
34  // the instance definition geometry and the archive
35  // (m_source_archive) containing the original defition.
37  {
38  static_def = 0,
39  embedded_def = 1,
40  // As of 7 February, "static_def" and "embedded_def"
41  // and shall be treated the same. Using "static_def"
42  // is prefered and "embedded_def" is obsolete.
43  // The geometry for the instance definition
44  // is saved in archives, is fixed and has no
45  // connection to a source archive.
46  // All source archive information should be
47  // empty strings and m_source_archive_checksum
48  // shoule be "zero".
49  linked_and_embedded_def = 2,
50  // The geometry for the instance definition
51  // is saved in archives. Complete source
52  // archive and checksum information will be
53  // present. The document setting
54  // ON_3dmIOSettings.m_idef_link_update
55  // determines if, when and how the instance
56  // definition geometry is updated by reading the
57  // source archive.
58  linked_def = 3,
59  // The geometry for this instance definition
60  // is not saved in the archive that contains
61  // this instance definition. This instance
62  // definition geometry is imported from a
63  // "source archive" The "source archive" file
64  // name and checksum information are saved
65  // in m_source_archive and m_source_archive_checksum.
66  // If file named in m_source_archive is not available,
67  // then this instance definition is not valid and any
68  // references to it are not valid.
69  force_32bit_idef_update_type = 0xFFFFFFFF
70  };
71 
72  // Converts and integer into an IDEF_UPDATE_TYPE enum.
73  static IDEF_UPDATE_TYPE IdefUpdateType(int i);
74 
75  // Bits that identify subsets of the instance defintion
76  // fields. These bits are used to determine which fields to
77  // set when an ON_InstanceDefinition class is used to
78  // modify an existing instance definition.
79  enum
80  {
81  no_idef_settings = 0,
82  idef_name_setting = 1, // m_name
83  idef_description_setting = 2, // m_description
84  idef_url_setting = 4, // all m_url_* fields
85  idef_units_setting = 8, // m_us and m_unit_scale
86  idef_source_archive_setting = 0x10, // all m_source_*, layer style, update depth fields
87  idef_userdata_setting = 0x20,
88  all_idef_settings = 0xFFFFFFFF
89  };
90 
91 public:
94 
95  // virtual ON_Object overrides
96  ON_BOOL32 IsValid( ON_TextLog* text_log = NULL ) const;
97 
98  // virtual ON_Object::Dump override
99  void Dump( ON_TextLog& ) const;
100 
101  ON_BOOL32 Write(
102  ON_BinaryArchive& binary_archive
103  ) const;
104  ON_BOOL32 Read(
105  ON_BinaryArchive& binary_archive
106  );
107  ON::object_type ObjectType() const;
108  unsigned int SizeOf() const;
109 
110  // virtual ON_Geometry overrides
111  int Dimension() const;
112  ON_BOOL32 GetBBox(
113  double* boxmin,
114  double* boxmax,
115  int bGrowBox = false
116  ) const;
117  ON_BOOL32 Transform(
118  const ON_Xform& xform
119  );
120 
121  // virtual
122  ON_UUID ModelObjectId() const;
123 
124  // Interface
125  const wchar_t* Name() const;
126  void SetName( const wchar_t* name );
127 
128  const wchar_t* Description() const;
129  void SetDescription( const wchar_t* description );
130 
131  const wchar_t* URL() const;
132  void SetURL( const wchar_t* url );
133 
134  const wchar_t* URL_Tag() const;
135  void SetURL_Tag( const wchar_t* url_tag );
136 
137  ON_UUID Uuid() const;
138  void SetUuid( ON_UUID uuid );
139 
140  void SetBoundingBox( ON_BoundingBox bbox );
141 
142  // list of object ids in the instance geometry table.
144 
145  /*
146  Description:
147  If the instance definition is linked or embedded, use
148  SetSource to specify the source archive.
149  Parameters:
150  source_archive - [in] name of source archive
151  checksum - [in] check sum used to detect changed.
152  Generally, you will pass ON_CheckSum::UnsetCheckSum
153  for this argument and Rhino will handle setting
154  the checksum to the appropriate value at the appropriate
155  time.
156  source_type - [in]
157  If source_archive and checksum are empty, then
158  source_type is ignored and static_def will be used.
159  If source_archive is a nonempty string and checksum
160  is set, then source_type must be either
161  linked_and_embedded_def or linked_def. If you
162  are changing the source archive of a valid idef,
163  then simply pass this->IdefUpdateType().
164  Remarks:
165  See the IDEF_UPDATE_TYPE comments for more details.
166  */
167  void SetSourceArchive(
168  const wchar_t* source_archive,
169  ON_CheckSum checksum,
170  IDEF_UPDATE_TYPE update_type
171  );
172 
173  /*
174  Description:
175  Destroys all source archive information.
176  Specifically:
177  * m_source_archive is set to the empty string.
178  * m_source_bRelativePath is set to false
179  * The alternative source archive path is set
180  to the empty string.
181  * m_source_archive_checksum.Zero() is used to
182  destroy all checksum information.
183  * m_idef_update_type is set to static_def.
184  */
185  void DestroySourceArchive();
186 
187  /*
188  Returns:
189  Name of source archive.
190  */
191  const wchar_t* SourceArchive() const;
192 
193  /*
194  Returns:
195  Check sum of source archive.
196  */
197  ON_CheckSum SourceArchiveCheckSum() const;
198 
199  const ON_UnitSystem& UnitSystem() const;
200 
201  /*
202  Description:
203  Use this function to specify an alternate location to
204  look for a linked instance defininition archive if it
205  cannot be found in the location specified by m_source_archive.
206  Parameters:
207  alternate_source_archive_path - [in]
208  alterate location. pass null to delete the alternate path.
209  bRelativePath - [in]
210  true if alternate_source_archive_path is a relative path.
211  */
212  void SetAlternateSourceArchivePath(
213  const wchar_t* alternate_source_archive_path,
214  bool bRelativePath
215  );
216 
217  /*
218  Description:
219  If there is an alternate location to look for a linked instance
220  defininition archive when it cannot be found in the location
221  specified by m_source_archive, then function will return the
222  alterate location.
223  Parameters:
224  alternate_source_archive_path - [out]
225  bRelativePath - [out]
226  true if alternate_source_archive_path is a relative path.
227  */
228  bool GetAlternateSourceArchivePath(
229  ON_wString& alternate_source_archive_path,
230  bool& bRelativePath
231  ) const;
232  /*
233  Description:
234  Sets m_us and m_unit_scale.
235  */
236  void SetUnitSystem( ON::unit_system us );
237  void SetUnitSystem( const ON_UnitSystem& us );
238 
239  /*
240  Returns:
241  True if this is a linked instance definition with
242  layer settings information.
243  */
244  bool HasLinkedIdefLayerSettings() const;
245 
246  /*
247  Description:
248  Set linked instance definition reference file layer settings.
249  Parameters:
250  layer_settings - [in/out]
251  input: layer settings read from the linked file.
252  output: layer settings to use in the context of the idef.
253  */
254  void UpdateLinkedIdefReferenceFileLayerSettings( unsigned int layer_count, ON_Layer** layer_settings );
255 
256  /*
257  Description:
258  Set linked instance definition parent layer information.
259  Typically this is done just before the linked idef is
260  saved to a file.
261  Parameters:
262  linked_idef_parent_layer - [in]
263  */
264  void UpdateLinkedIdefParentLayerSettings( const ON_Layer* linked_idef_parent_layer );
265 
266  const ON_Layer* LinkedIdefParentLayerSettings() const;
267 
268  /*
269  Description:
270  When a linked instance definition is read and its layers are added to the
271  context when the idef exists, runtime layer ids may need to be changed
272  when an id collision occures. In this case, use this function to
273  inform the linked instance definition of the map from runtime layer
274  id to the layer id found in the linked file.
275  Parameters:
276  id_map - [in]
277  The first id in the pair is the layer id in the current context
278  where the idef is being used.
279  The second id in the pair is the layer id found in the linked file.
280  */
281  void UpdateLinkedIdefReferenceFileLayerRuntimeId( const ON_UuidPairList& id_map );
282 
283  /*
284  Description:
285  Set linked instance definition layer settings.
286  Typically this is done just before the linked idef is
287  saved to a file.
288  Parameters:
289  layer_settings - [in]
290  Layer settings in the context where the linked idef is being used.
291  Remarks:
292  Linked idefs save the original layer informtion from the linked file.
293  In the context where the idef is used, some of those settings (color,
294  visibility, ...) can be modified. This function saves those modifications
295  so the can be applied the next time the linked idef is read.
296  */
297  void UpdateLinkedIdefLayerSettings( unsigned int layer_count, const ON_Layer*const* layer_settings );
298 
299 public:
300 
301  ON_UUID m_uuid; // unique id for this instance definition
302  ON_wString m_name; // The "name" is for human comfort.
303  // It can be empty and duplicates
304  // may exist. Instance reference use
305  // m_uuid to find instance definitions.
307 
309  ON_wString m_url_tag; // UI link text for m_url
310 
311 #if defined(ON_32BIT_POINTER)
312 private:
313  // 24 January 2011:
314  // Because the Rhino 4 and 5 SDKs are fixed, the offset of
315  // existing fields cannot be changed and the m_reserved1
316  // value has to be located in different places for
317  // 32 and 64 bit builds.
318  unsigned int m_reserved1;
319 #endif
320 
321 public:
323 
325 
326  // Note: the embedded_def type is obsolete.
327  // To avoid having to deal with this obsolete type in
328  // your code, using ON_InstanceDefintion::IdefUpdateType()
329  // to get this value. The IdefUpdateType() function
330  // with convert the obsolte value to the correct
331  // value.
333 
334  IDEF_UPDATE_TYPE IdefUpdateType() const;
335 
336  int m_idef_update_depth; // Controls how much geometry is read when
337  // a linked idef is updated.
338  // 0: read everything, included nested linked idefs
339  // 1: skip nested linked idefs.
340 
341  ON_wString m_source_archive; // filename used to update idef
342  // (it can be empty or relative)
343  bool m_source_bRelativePath; // True if the filename in m_source_archive is
344  // a relative the location of the 3dm file
345  // containing this instance definition.
346 
347  // A static or linked_and_embedded idef must have m_layer_style = 0
348  // A linked idef must have m_layer_style = 1 or 2
349  // 0 = unset
350  // 1 = active (linked idef layers will be active)
351  // 2 = reference (linked idef layers will be reference)
352  unsigned char m_idef_layer_style;
353 
354 private:
355  unsigned char m_reserved2[2];
356 
357 #if defined(ON_64BIT_POINTER)
358 private:
359  // 24 January 2011:
360  // Because the Rhino 4 and 5 SDKs are fixed, the offset of
361  // existing fields cannot be changed and the m_runtime_sn
362  // value has to be located in different places for
363  // 32 and 64 bit builds.
364  unsigned int m_reserved1;
365 #endif
366 
367 public:
368  ON_CheckSum m_source_archive_checksum; // used to detect when idef is out of
369  // synch with source archive.
370 };
371 
372 
373 /*
374 Description:
375  An ON_InstanceRef is a reference to an instance definition
376  along with transformation to apply to the definition.
377 See Also:
378  ON_InstanceRef
379 */
380 class ON_CLASS ON_InstanceRef : public ON_Geometry
381 {
382  ON_OBJECT_DECLARE(ON_InstanceRef);
383 
384 public:
385  ON_InstanceRef();
386 
387  /////////////////////////////////////////////////////////////
388  //
389  // virtual ON_Object overrides
390  //
391  ON_BOOL32 IsValid( ON_TextLog* text_log = NULL ) const;
392  ON_BOOL32 Write(
393  ON_BinaryArchive& binary_archive
394  ) const;
395  ON_BOOL32 Read(
396  ON_BinaryArchive& binary_archive
397  );
398  ON::object_type ObjectType() const;
399 
400  /////////////////////////////////////////////////////////////
401  //
402  // virtual ON_Geometry overrides
403  //
404  int Dimension() const;
405  ON_BOOL32 GetBBox(
406  double* boxmin,
407  double* boxmax,
408  int bGrowBox = false
409  ) const;
410  ON_BOOL32 Transform(
411  const ON_Xform& xform
412  );
413 
414  // virtual ON_Geometry::IsDeformable() override
415  bool IsDeformable() const;
416 
417  // virtual ON_Geometry::MakeDeformable() override
418  bool MakeDeformable();
419 
420  /////////////////////////////////////////////////////////////
421  //
422 
423  // Unique id of the instance definition (ON_InstanceDefinition)
424  // in the instance definition table that defines the geometry
425  // used by this reference.
427 
428  // Transformation for this reference.
430 
431  // Bounding box for this reference.
433 
434  // Tolerance to use for flagging instance xforms
435  // as singular.
436  static const double m_singular_xform_tol;
437 };
438 
439 #endif
virtual ON_BOOL32 IsValid(ON_TextLog *text_log=NULL) const =0
static const double m_singular_xform_tol
virtual ON_BOOL32 Transform(const ON_Xform &xform)
virtual bool MakeDeformable()
virtual ON_BOOL32 Write(ON_BinaryArchive &binary_archive) const
virtual ON::object_type ObjectType() const
IDEF_UPDATE_TYPE m_idef_update_type
ON_UUID m_instance_definition_uuid
virtual int Dimension() const =0
virtual ON_BOOL32 Read(ON_BinaryArchive &binary_archive)
virtual unsigned int SizeOf() const
ON_BoundingBox m_bbox
unsigned char m_idef_layer_style
ON_CheckSum m_source_archive_checksum
virtual void Dump(ON_TextLog &) const
virtual bool IsDeformable() const
ON_SimpleArray< ON_UUID > m_object_uuid
virtual ON_UUID ModelObjectId() const
virtual ON_BOOL32 GetBBox(double *boxmin, double *boxmax, int bGrowBox=false) const =0