doc/salome/kernel_salome.dox

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