View source for Adding models to catalogued volumes

A file representing a model created on a catalogued tomogram will be stored in a predefined position. For instance, a [[model]] named {{t|someModel}} created by ''Dynamo'' in one of its catalogue-based  [[Viewing tomograms|tomogram viewers]] for the volume indexed as 2 in a [[catalogue]] named {{t|myCatalogue}} will be automatically stored in the position:

{{t| myCatalogue/volume_2/models/someModel.omd}} 

=== Entering a model file into a catalogue===

Now, if you have produced  a model object {{t|myModel}} independently from the catalogue system, and want to embed it and assign it to a catalogued tomogram, you might have the temptation of just saving it as

{{t| dwrite(myModel,'myCatalogue/volume_2/models/myModel.omd')}}.

While this will work for many functionalities, this is not totally correct, as the catalogue needs to preserve some internal links.
# Assign the model with the {{t|dcm}} command {{docfunction|dynamo_catalogue_manager|dcm}}
#: {{t|dcm -c myCatalogue -i 2 -am myModel.omd}}
#: for a models contained in a file {{t|myModel.omd}}, or
#: {{t|dcm('-c', 'myCatalogue', '-i', 2 ,'-am', m);}}
#: if the model is contained in an workspace object {{t|m}}
# Alternatively, you can tell the catalogue to relink all the files found in the models folder of one or more volumes.
#: {{t|dcm -c myCatalogue --relinkAllModelFiles}}
#: ''warning'': this feature is not yet fully implemented.


=== Direct assignment of model object===

Sometimes you want with work with model objects inside the Matlab/Standalone workspace, in order to create and manipulate them directly. In such cases, you can first link a model with a catalogued volume (with method {{t|linkCatalogue}}) and then save it into the catalogue (with method {{t|linkCataloguedVolume}}).

For instance, with the following excerpt of code you can define a vesicle model and link it into the volume with index '1' inside the catalogue 'myCatalogue'
 <nowiki>
v = dmodels.vesicle();
v.center = [100,100,150];
v.radius = 50;
v.name = 'myManualVesicle';
v.linkCatalogue('myCatalogue','i',1);
v.saveInCatalogue();
</nowiki>

Note that a model is '''not''' directly linked to a catalogue. You need to specify to which tomogram in the catalogue it is linked. Also, linking to the catalogued tomogram by itself will not save the object in disk. You need to invoked afterwards the method {{t|saveInCatalogue}}, or to use the flag 'save','s'  inside {{t|linkCatalogue}} with value 1, i.e.

 <tt>v.linkCatalogue('myCatalogue','i',1,'s',1);</tt>


{{Technicality}}

The link between a model and its 'volume' entry happens over the property {{t|cvolume}} in the {{t|model}} object. If you want to imitate manually the action of the flag {{t|am}}, you just need to extract the corresponding 'cvolume' object of the catalogue and assign it to the 'cvolume' property of the model before saving it.

When working inside a catalogue and accessing a model file from a volume, ''Dynamo'' will normally relink the model so that it points to the calling volume. For such operations, the above described protocol is not necessary.