Occult Watcher

--> The "Scan Tracker" Addin
--> Lunar Occultations for OccultWatcher Addin
--> Occult Tools for OccultWatcher Addin
--> The "IOTA Reporting" Addin
--> The "NEA Alerter" Addin
--> What other extra addins are currently available
--> How to develop your own Add-ins for OccultWatcher

OccultWatcher allows you to extend its functionally by developing custom Add-ins (or plug-ins). The C2A Add-in which is part of the standard distribution of OccultWatcher is an example of such an extension. The C2A Add-in adds the great functionality of plotting occultation charts with a single click from within OccultWatcher. Another standard add-in which has been made part of OccultWatcher is the IOTA Reporting Add-in.

The "Scan Tracker" Addin

The Scan Tracker Add-in will make it possible for people that are using the Scan Tracker software to export their "My Sites" from Occult Watcher so they can be used within Scan Tracker. The Scan Tracker software is part of the Drift-Scan observation suite as designed by John Broughton.

The add-in can be downloaded from here

Lunar Occultations for Occult Watcher

The Lunar Occultations Add-in will make it possible for people that have Occult installed on the same computer as OccultWatcher to get in OW interesting lunar occultations involving double and suspected double stars. The events are carefully selected by a number of people around the world that run predictions for their local areas. If you are interested in running such a feed of double star lunar occultations in your area please contact the author of OccultWatcher.

The add-in can be downloaded from here and needs to be unzipped and copied to your Occult Watcher location. After a restart a new feed called "Lunar Occultations of Close Double Stars" will show up in the feeds list. Before you can use the feed you will need to configure the feed location and the Occult4 directory. Use Add-ins -> Configure Add-ins -> Lunar Occultations for OccultWatcher and complete the configuration.

At the moment the following feeds are available and you will need to configure the URL of the feed you want to use in the form above:

Occultations for the Australia and New Zealand area maintained by Brian Loader and hosted by Hristo Pavlov at:
http://www.hristopavlov.net/LunarWatcher/index.txt

Occultations for the Europe region maintained by Oliver Klös and Jan Manek and hosted by IOTA-ES at:
http://www.iota-es.de/OWFeed/EuroDls.txt

Occultations for South America maintained by Néstor D. Díaz and hosted by GEDRAA at:
http://www.gedraa.com.ar/lunar/SAmerica.txt

You will need to restart OccultWatcher after you complete the configuration for the changes to take effect. After that you can synchronise and get events similar to the ones shown below. If you double click on an event Occult4 will pop up and will show the Moon map with the location of the star and the local circumstances of the event. OccultWatcher also calculated the exact local circumstances at the time of the synchronisation using the currently selected home location in OW.

Occult Tools for OccultWatcher

Occult Tools for OccultWatcher is an add-in that allows people that use Occult to start some of the Occult functionality for a selected event in OccultWatcher. The add-in can be downloaded here. You then need to configure the directory where your Occult is installed. You can do this from Add-ins -> Configure Add-ins -> Occult Tools for OccultWatcher.

Occult ver. 4.0.8.15 or later is required for the add-in to work. In version 1.0 of the add-in the two commands that can be used are the Star Catalogue Comparison form and the Open Event in Occult. To use them, select an event, then right click and click the desired menu item.

For more information on how to use the Compare Star Catalogues and the Event Summary forms please refer to Occult's help file.

The IOTA Reporting add-in has been made part of the standard OccultWatcher installation since version 3.2. It can help you prepare your official asteroidal occultation report by prefilling most of the information such as your contact details and the event details: star name, asteroid name and number, event time, your equipment parameters etc. Further more for regions that use excel files for reporting, the IOTA Reporting add-in checks if the observed times are entered correctly and warns you if they are more than a minute away from the predicted time. The add-in will only prepopulate your report and you are still required to send your finalized report to your regional coordinator.

There are two ways to initiate the observation form pre-filling. In both cases you need to have an Observation Planner account setup and you need to have announced your station.

After the event has passed when you right click on the event in the list, the "Report Observation" menu item will be enabled.

Then if this is your first report (i.e. you haven't reported your observation yet) you will have to go through the standard reporting process. Please note that this reporting is for OW users only and is not an official report. After you have completed the report you will be asked whether you want to prepare your official report. Answering "Yes" will start the IOTA Reporting Add-in.

The second way to run the IOTA Reporting Add-in is if you have already reported your observation in OccultWatcher. Then you again right click and choose "Report Observation". When the form shows up you need to select the station you want to prepare your official report for. When the station is selected a "Prefill Report File" button will appear. Pressing this button will start the IOTA Reporting Add-in.

Different regions use different reporting forms and processes. At the moment the IOTA Reporting Add-in can help you prefill your form if you are in Europe, Americas, Australia or Africa. Before you start you will have to select your reporting region.

For Europe, all observations are reported in a text format and the content requirements are not very strict. Still the most important fields such as position and occultation timing are mandatory. The IOTA Reporting Add-in can help you prefill your observation report by maintaining a library of templates for your different stations and/or equipment. Those templates will tipically have most of the information not related to the observation populated already and will contain some special tokens, which OccultWatcher will replace with the real values for the corresponding event when you prefill the report. The list of all available tokens is shown below.

Use the New, Edit and Delete buttons to manage your report templates and press "Prefill Report" to prepare your official report.

The image below shows how the standard template for Europe looks like.

The Americas, Australia and Africa regions are using a Microsoft Excel based report form as well as a text form. The IOTA Reporting Add-in supports the Excel form only.

The advantage of using an Excel form is that the positions for the various details are already fixed and known and there is no need to use tokens as was the case with the European report form. Further more the IOTA Reporting Add-in can do a validation of your entered times and find errors when the times are reported an hour or a minite before/after the actual times.

Instead of library of templates, in the case of Excel form reports, the IOTA Reporting Add-in stores a library of configurations as shown below. To prepare your report you need to select the right configuration and press "Prefill Report".

The image below a prefilled excel report. The only fields left for the observer in this case are the times of the event and the observing conditions. Once the file is saved and closed, the IOTA Reporting Add-in will run a validation on your entered times and may show you warning messages if something doesn't look quite right.

The "IOTA Reporting" add-in doesn't send your report to your regional coordinator. You will still need to do that by email.

OccultWatcher.NEA

This new add-in monitors the newly discovered Near Earth Objects as well as the known Near Earth Objects and alerts you for upcoming close approaches to the Earth that could be a good oportunity for doing Video Astrometry for example with Tangra.

The add-in can be downloaded here. You need to extract it in the Occult Watcher's install location.

At the moment there is one extra addin for OccultWatcher ("OW Little Helpers") which is not part of the standard deployment of OccultWatcher and needs to be downloaded and installed manually. The OW Little Helpers Add-in includes the following functionality:

1) Looking up whether a given SAO star is included in the Meade Autostar database (used by Meader LX-90 and including 17895 bright SAO stars).
I use this to identify the closest SAO star and slew to it before I do star-hopping to the target.
2) Copying the event details for a given event in a compact format to be used as a reference (ex. printed on your custom star charts)

To install the "OW Little Helpers" add-in follow these steps:

- Download the add-in
- Stop your running OccultWatcher
- Unzip the downloaded file to your OccultWatcher directory
- Restart OccultWatcher

You will now have two new items under "Add-ins": "Meade SAO Star Search" and "Copy Event Details"

The "Meade SAO Star Search" will show up a form and ask you to enter a SAO star number. If you already have the number in your clipboard it will use the value from the clipboard as a default value. After you press "Find" if the star is found it will display its coordinates and magnitude.

"Copy Event Details" could be executed from both the "Add-in" menu and the evens list context menu. It will simply copy information about the event in our clipboard and display it. You can then paste it in other programs.

The type and the format of the information copied in the clipboard can be customized from Add-ins -> Configure Add-ins menu. You will be able to edit the template of the text being coppied and can insert various tags that will be replaced with the real values for the selected event. To insert a new tag use the "Insert Tag" button or type the name of the tag if you know it. All tags start and end with a percent character [ % ].

Developing Add-ins for OccultWatcher

If you want to develop your own add-in this page will provide you with the technical information you will need. I have tried to provide very in-depth information so if you don't understand everything (especially if you are new to .NET) then don't worry. Writing an add-in is very simple. Take your time, have a look at the sample code and you can figure out what to do even without reading the information below. The idea of this page is to give you an overview of how add-ins function and integrate with OccultWatcher and also to be used as advanced programming reference for people that want to achieve maximum results.

OccultWatcher is developed using Microsoft .NET Framework 2.0 and the best way to implement add-ins is by using the same technology. Alternately you could implement your add-in as a COM object or an exported function from a DLL using C++, VB6 or other language and then use a simple .NET wrapper which will call your objects/functions from .NET using COM Interop or PI-Invoke. If you know how to do the part in C++ or VB6 but you don't know how to implement the wrapper class in .NET then I can help you with that.

So I will assume that you are implementing the Add-in in .NET and will talk about what you need to do. The same guidelines apply for implementing the wrapper class I mentioned above. So first of all you should download the OccultWatcher SDK. It contains the source code of the file OccultWatcher.SDK.dll which is part of the standard distribution of OccultWatcher and also the full source code of the "OW Little Helpers" add-in which you can use as a reference.

An add-in for OccultWatcher is simply a class that implements the IOWAddin interface and resides in assembly that is copied to the same folder as OccultWatcher. When OccultWatcher starts up it loads all DLL files from the same folder, checks if they are .NET assemblies, then enumerates all classes exposed by those assemblies and checks whether any of them implements the IOWAddin interface. Those classes will be loaded as Add-ins.

After OccultWatcher has enumerated all classes that implement an add-in it will instantiate each of them and will call InitializeAddin(). Then it will retrieve the supported Add-in actions by calling SupportedActions() for each of the add-ins. There are 3 types of actions and they are defined by the OWAddinActionType enum.

AllEventsAction is an action that doesn't operate on any specific event and is enabled at all times. Such an action is the "Meade SAO Stars Search" from OW Little Helpers.

Then the SelectedEventAction operates on the currently selected event and is only enabled when there is a selected event. Such an action is the "Create C2A Occultation Map" from the standard C2A Add-in.

And finally there is an action type called EventReceiver which allows you to define event handler for some events raised by OccultWatcher. These events are defined by the OWEventArguments class and currently include: event indicating when asteroidal occultation events are added by the filer, the analysis has started or completed, the main form has moved or has changed its state or when the current language has been changed by the user. The language change event can be used by your add-in for loading localized settings. If you have an idea for an add-in that requires another event not listed here then I could be able to add it for you if that's possible.

OccultWatcher will create a menu item under "Add-ins" for each AllEventsAction and then will create a menu item under "Add-ins" and also in the events list context menu for each SelectedEventAction. Every time one of these two menus are shown (dropped down or popped up) OccultWatcher will call ShouldDisplayAction() for each SelectedEventAction to determine whether the action should be enabled/disabled for the particular event. This allows you to create actions that operate only on specific asteroidal events.

When the user clicks on one of the menu items representing an add-in action, OccultWatcher will call ExecuteAction() passing the action ID and also some other parameters. Note that the parameter IOWAsteroidEvent astEvent actually implements more than one interface. .NET allows you to cast this IOWAsteroidEvent object to those other interfaces directly by using the "as" operator or an explicit cast. The other two interfaces implemented by astEvent are IOWLocalEventData and IOWUserConfig and you can use them to get local data for the current site in OW or current OW configuration info such as site coordinates, local event time, star altitude, configuration settings etc. Check out the interface members from the SDK for more information.

If you need your Add-in to have your own configuration settings and you want the user to be able to configure it then you should set SupportsConfiguration = true in the OWAddinInfo structure you return by GetAddinInfo(). Then OccultWatcher will add a sub-menu under "Add-ins" -> "Configure Add-ins" for your add-in and will call Configure() when the user clicks on the sub-menu item. It's up to you to save and load your configuration settings. If you choose to use the .NET Isolated File Storage to save/load your configuration setting from then bear in mind that every time you change your assembly version you will effectively reset your configuration and your new assembly will not be able to read the settings from the old version. To avoid this you should consider not changing the assembly version of your add-in at all but instead vary the file version.

OccultWatcher also gives you ability to automatically upgrade your Add-in when you want to publish a new version. The only thing you need to do is to specify the file url where you are going to publish the new versions of the add-in as the UpdateUrl member of the OWAddinInfo structure you return by GetAddinInfo(). Every time OccultWatcher checks for updates it will also check the specified UpdateUrls for all registered add-ins and if a new version of the add-ins is available. Then it will download the file and upgrade the add-in.

You can provide an UpdateUrl to a zip or a dll file. Urls pointing to other file types will be ignored. If you provide a zip file then OccultWatcher will extract all files including the directory structure in the OccultWatcher execution location. Please note that OW will use the HTTP headers to determine whether a new version of the file is available on the web server before proceeding with a download. Then it will check the assembly version and the file version of the assembly that exposes your add-in before proceeding with an upgrade. So make sure you increase your file version (or/and assembly version) of your new version for the upgrade to work properly.

The IOWAddin interface contains the following members:


        /// 

        /// InitializeAddin() is called after the addin is loaded from OccultWatcher.

        /// It will be also called when the Add-ins are reinitialized when the current language settings are changed.

        /// In this method you will typically initialize any shared resources you are going to use from your addin actions.

        /// 


        void InitializeAddin(IOWHost hostInfo);

        

        


        /// 

        /// FinalizeAddin() is called by OccultWatcher when it is about to shut down normally.

        /// It will be also called when the Add-ins are reinitialized when the current language settings have changed.

        /// Note that during the updates it is possible that FinalizeAddin() may not be called and in such a case 

        /// OccultWatcher will restart without notice to the loaded addins

        /// 


        void FinalizeAddin();

        

        

        
        /// 

        /// Return information about the addin.

        /// 


        OWAddinInfo GetAddinInfo();
        

        


        /// 

        /// You can show your own configuration forms in this method

        /// 


        /// owner: OccultWatcher main window handle

        /// 

        void Configure(IWin32Window owner);

        

        

  
        /// 

        /// Returns a list of the supported actions. They must have unique IDs.

        /// 


        /// returns: List of the supported actions

        /// 

        IEnumerable<OWAddinAction> SupportedActions();

        

        

  
        /// 

        /// This method is called by OccultWatcher before displaying the menu item link

        /// that triggers this event. This is a good place to determine whether this action

        /// should be enabled or disabled for the selected event.

        /// 


        /// actionId: The action addin as specified in the OWAddinAction structure returned by SupportedActions()

        /// astEvent: The currently selected event in OccultWatcher

        /// returns: true if the action should be displayed (enabled/visible) for this event, otherwise false

        /// 

        bool ShouldDisplayAction(int actionId, IOWAsteroidEvent astEvent);

        

        

  
        /// 

        /// This is the main method in your addin. This is where you run your custom code to do the useful

        /// things you want to do.

        /// 


        /// actionId: The action addin as specified in the OWAddinAction structure returned by SupportedActions()

        /// astEvent: The currently selected event in OccultWatcher

        /// owner: OccultWatcher main window handle

        /// eventArgs: In a case of event receiver action this are the event arguments

        /// 

        void ExecuteAction(int actionId, IOWAsteroidEvent astEvent, IWin32Window owner, OWEventArguments eventArgs);

Have a look at how OW Little Helpers add-in implements all those members for some more clues and if you end up implementing an add-in that you think may be useful to the others, please contact me and I will put it for download on this page! If you have any additional questions - don't hesitate to contact me and I will be glad to help.

Happy coding!

Occult Watcher 3.2

The "Scan Tracker" Addin

Lunar Occultations for Occult Watcher

Occult Tools for OccultWatcher

OccultWatcher.NEA