doc/salome/kernel_salome.dox

   1 /*!
   2
   3 \page kernel_salome Using salome.py module
   4
   5
   6 The salome.py Python module provides a set of variables and functions
   7 allowing access to different elements of the current SALOME
   8 session.
   9 This page gives a short description of most useful variables and
  10 functions.
  11
  12 \li \b orb Reference to the CORBA::ORB instance
  13
  14 This variable can be used to initialize different CORBA-related
  15 elements of the SALOME session (for example, naming service, etc).
  16 For example, to get an access to the SALOME naming service, you can
  17 use the following commands:
  18 \code
  19 import SALOME_NamingServicePy
  20 NS = SALOME_NamingServicePy.SALOME_NamingServicePy_i(salome.orb)
  21 \endcode
  22
  23 The \b orb variable is also useful when it is necessary to convert
  24 CORBA reference object to its string representation (IOR) and vice
  25 versa:
  26 \code
  27 studyIOR = salome.orb.object_to_string(salome.myStudy)
  28 study    = salome.orb.string_to_object(studyIOR)
  29 is_same  = salome.myStudy._is_equivalent(study) # is_same = True
  30 \endcode
  31
  32 \li \b naming_service SALOME naming service instance
  33
  34 This variable can be used to register/find objects created in a
  35 distributed environment. For example, to get access to the SALOME
  36 Module Catalog server, use \c Resolve() method:
  37 \code
  38 import SALOME_ModuleCatalog
  39 mc = salome.naming_service.Resolve('/Kernel/ModulCatalog')
  40 \endcode
  41
  42 Similarly, method \c Register() can be used to register objects
  43 in the naming service:
  44 \code
  45 salome.naming_service.Register(myObject,'/My/Object/Path')
  46 o = salome.naming_service.Resolve('/My/Object/Path')
  47 is_same = myObject._is_equivalent(o) # is_same = True
  48 \endcode
  49
  50 \li \b lcc Life Cycle CORBA class instance
  51
  52 This object can be used to get access to CORBA engine part of some
  53 SALOME module, available in the current SALOME session. The following
  54 code returns a reference to the Geometry module engine, loading it if
  55 necessary:
  56 \code
  57 import GEOM
  58 geom = salome.lcc.FindOrLoadComponent('FactoryServer', 'GEOM')
  59 \endcode
  60 \b Note, that in the above example, \e "FactoryServer" is a name of the
  61 SALOME container, where Geometry module engine should be loaded.
  62
  63 \li \b myStudyManager Reference to the study manager
  64
  65 SALOMEDS Study manager is used to manipulate with the studies: create,
  66 open, save, close. It also can be used to find the study by its
  67 numerical ID or name. The code below demonstrates main
  68 functionalities of a study manager:
  69 \code
  70 # create new study with the name "MyStudy"
  71 new_study = salome.myStudyManager.NewStudy("MyStudy")
  72
  73 # open study from file /home/user/MyStudy.hdf
  74 study = salome.myStudyManager.OpenStudy("/home/user/MyStudy.hdf")
  75
  76 # save study
  77 salome.myStudyManager.Save(study, False) # not using multifile save mode
  78
  79 # save study in ASCII format
  80 salome.myStudyManager.SaveASCII(study, True) # using multifile save mode
  81
  82 # save study with the new file path
  83 salome.myStudyManager.SaveAs("/home/user/MyStudy.hdf", study, False)
  84
  85 # save study with the new file path in ASCII format
  86 salome.myStudyManager.SaveAsASCII("/home/user/MyStudy.hdf", study, False)
  87
  88 # close study
  89 salome.myStudyManager.Close(study)
  90
  91 # get list of all opened studies
  92 studies = salome.myStudyManager.GetOpenStudies()
  93
  94 # find study by its numerical ID (integer value starting from 1)
  95 study = salome.myStudyManager.GetStudyByID(studyID)
  96
  97 # find study by its name
  98 study = salome.myStudyManager.GetStudyByName("/home/user/MyStudy.hdf")
  99
 100 # ...
 101 \endcode
 102
 103 \li \b myStudy Reference to the current (active) study
 104
 105 This variable can be used to manipulate with the date of the study:
 106 create data tree, assign attributes of different types to the objects
 107 in a data tree, create references between objects, etc.
 108
 109 \b Note, that the term "active" or "current" study does not make much
 110 sense outise the GUI Python console. When working in GUI, user always
 111 deals with one only top-level study, which desktop is currently on the
 112 top if the windows stack. This is what is called \e "active study".
 113 In TUI mode (without GUI or outside GUI), user has to manipulate with
 114 studies manually; no any special control for the life cycle of the
 115 study is done. In TUI mode, \c salome.muStudy variable is an instance
 116 of the first study created when you call salome_init() function.
 117
 118 The following code demonstrates some examples of \c salome.myStudy
 119 variable usage. For more details please refer to the SALOMEDS.idl file
 120 documentation.
 121
 122 \code
 123 # get study name
 124 studyName = salome.myStudy._get_Name()
 125
 126 # get study numerical ID
 127 studyID = salome.myStudy._get_StudyId()
 128
 129 # find SALOMEDS component by its type
 130 scomponent = FindComponent("MyComponent")
 131
 132 # find SALOMEDS component by its entry ID
 133 scomponent = FindComponentID("0:1:1") # "0:1:1" is a component ID
 134
 135 # find SALOMEDS object by its name (first found object is returned)
 136 sobject = salome.myStudy.FindObject("MyObject")
 137
 138 # find SALOMEDS object by its entry ID
 139 sobject = salome.myStudy.FindObjectID() # "0:1:1:1" is an object ID
 140
 141 # find SALOMEDS object by its IOR attribute
 142 sobject = salome.myStudy.FindObjectIOR(IOR)
 143
 144 # find SALOMEDS object by its path in the data tree
 145 sobject = salome.myStudy.FindObjectByPath("/MyComponent/MyObject/MySubObject")
 146
 147 # get SALOMEDS object's path in a study data tree
 148 sobject_path = salome.myStudy.GetObjectPath(sobject)
 149
 150 # get study properties
 151 prop = salome.myStudy.GetProperties()
 152 prop.GetCreationDate() # get creation date
 153 prop.IsModified() # check if study has been modified (and not yet saved)
 154 prop.SetLocked(True) # lock the study (prohibit modifications)
 155 prop.IsLocked() # check if study is locked
 156
 157 # create objects with study builder
 158 builder = salome.myStudy.NewBuilder() # create builder
 159 comp = builder.NewComponent("MyComponent") # create a component of the "MyComponent" type
 160 attrName = builder.FindOrCreateAttribute(comp, "AttributeName")
 161 attrName.SetValue("MyComponent") # set name to the component
 162 object = builder.NewObject(comp) # create new object, a child of the component
 163 attrName = builder.FindOrCreateAttribute(object, "AttributeName")
 164 attrName.SetValue("MyObject") # set name to the object
 165 attrInt = builder.FindOrCreateAttribute(object, "AttributeInteger")
 166 attrInt.SetValue(123) # assign integer attribute to the object
 167 attrIOR = builder.FindOrCreateAttribute(object, "AttributeIOR")
 168 attrIOR.SetValue(IOR) # assign IOR attribute to the object (to point to some CORBA object)
 169
 170 # iterate through objects of the data tree with child iterator
 171 iter = salome.myStudy.NewChildIterator(comp) # initialize from the component
 172 iter.InitEx(True) # init recursive mode
 173 while iter.More():
 174       c = iter.Value()
 175       print c.GetID()
 176       iter.Next()
 177       pass
 178
 179 # ...
 180 \endcode
 181
 182 \li \b myStudyId Identifier of the current (active) study
 183
 184 This variable contains the numerical identifier of the current
 185 (active) study. It is an equivalent of \c
 186 salome.myStudy._get_StudyId() code.
 187
 188 \li \b myStudyName Name of the current (active) study
 189
 190 This variable contains the name of the current (active) study. It is
 191 an equivalent of \c salome.myStudy._get_Name() code.
 192
 193 \li \b DumpStudy() Print study contents
 194
 195 This function prints the study data object tree to the terminal
 196 window. The output for each object includes its entry ID, name, IOR
 197 (if there is one) and referenced object ID (for references). I.e.
 198 this is the same data the user can see in the Object Browser columns.
 199 \code
 200 salome.DumpStudy(salome.myStudy)
 201 \endcode
 202
 203 \li \b IDToSObject() Get SALOMEDS object by its entry ID.
 204
 205 This function checks if the SObject with the specified entry ID exists
 206 in the current study and returns it. Otherwise \c None is returned.
 207 \code
 208 sobject = salome.IDToSObject("0:1:1:1") # "0:1:1:1" is an object ID
 209 \endcode
 210 Actually this function is just a shortcut to the following code:
 211 \code
 212 sobject = salome.myStudy.FindObjectID("0:1:1:1")
 213 \endcode
 214
 215 \li \b IDToObject() Get CORBA object by its entry ID.
 216
 217 This function checks if the SObject with the specified entry ID exists
 218 in the current study, then retrieves IOR attribute from it and,
 219 finally, if IOR is not empty, returns CORBA object corresponding to
 220 the found SObject:
 221 \code
 222 object = salome.IDToObject("0:1:1:1") # "0:1:1:1" is an object ID
 223 \endcode
 224 Actually this function is just a shortcut to the following code:
 225 \code
 226 sobject = salome.myStudy.FindObjectID("0:1:1:1")
 227 if sobject:
 228    object = sobject.GetObject()
 229 else:
 230    object = None
 231 \endcode
 232
 233 \li \b ObjectToSObject() Get SALOMEDS object corresponding to the
 234 CORBA object.
 235
 236 This function finds an object in the current study which corresponds
 237 to the specified CORBA object (i.e. it has IOR attribute, pointing to
 238 the CORBA object). If there is no corresponding SALOMEDS object in the
 239 study, \c None is returned:
 240 \code
 241 sobject = salome.ObjectToSObject(object)
 242 \endcode
 243 Actually this function is just a shortcut to the following code:
 244 \code
 245 ior = salome.orb.object_to_string(object)
 246 sobject = salome.myStudy.FindObjectIOR(ior)
 247 \endcode
 248
 249 \li \b ObjectToID() Get SALOMEDS object entry ID corresponding to the
 250 CORBA object.
 251
 252 This function finds an object in the current study which corresponds
 253 to the specified CORBA object (i.e. it has IOR attribute, pointing to
 254 the CORBA object). If the object is found, its entry ID is returned,
 255 otherwise empty string is returned:
 256 \code
 257 entry = salome.ObjectToID(object)
 258 \endcode
 259 Actually this function is just a shortcut to the following code:
 260 \code
 261 ior = salome.orb.object_to_string(object)
 262 sobject = salome.myStudy.FindObjectIOR(ior)
 263 if sobject:
 264    entry = sobject.GetID()
 265 else:
 266    entry = ""
 267 \endcode
 268
 269 \li \b createNewStudy() Create new study
 270
 271 This function can be used to create new SALOME study. Returns an ID of
 272 the created study.
 273 \code
 274 studyId = salome.createNewStudy()
 275 study   = salome.myStudyManager.GetStudyByID(s)
 276 \endcode
 277
 278 \li \b generateName() Generate unique name
 279
 280 This function adds random numerical suffix to the passed string
 281 parameter ("Study" by default) and returns the resulting string:
 282 \code
 283 name_1 = salome.generateName() # name_1 is something like "Study682"
 284 name_1 = salome.generateName("Obj") # name_1 is something like "Obj32"
 285 \endcode
 286
 287 \li \b sg SWIG interface to the SALOME GUI
 288
 289 This variable provides an access to some GUI functions.
 290
 291 \b Note, that this variable is only available if you use salome.py
 292 Python module within the GUI desktop (since SWIG library is linked directly to the GUI library).
 293 See GUI documentation for more information.
 294
 295
 296 */