﻿--------------------------------
Radio Meteor Activity Projection
--------------------------------

The Radio Meteor Observation Bulletin (RMOB) web site (www.rmob.org) collects information on Radio Meteor Reflection
counts that have been registered by several observers around the world.

This information is recorded in RMOB Survey files, which is a time based format. The sample data content is composed
by a matrix of hours versus days. A meteor reflection count for every UTC hour of every day in a month is provided.

The RMOB File contains observer's related information, as latitude and longitude. With the UTC time, the date and the 
Longitude information of the observer, it is possible to calculate the Julian Day (Julian Day calculation from Jean 
Meeus, (1991), “Astronomical Algorithms“) and the Local Sideral Time (LST) (Local Sideral Time calculation from Simon 
Newcomb Sideral Time formula) of the observer at the UTC hour of the count, and consequently, the Right Ascension (RA)
of the local meridian of the observer at that time. The declination is directly obtained from the Observer's Latitude.

The observer's count for every UTC hour is normalized using the own observer's average figure calculated over a complete 
month of data. With the RA and Dec calculated as indicated before, we have the observer's zenit at the UTC time of every
count (in fact, the zenit is calculated based on UTC + 30 minutes, to have a centered representation for every UTC hour). 
Once the zenit is in this way located, a square of 15º by 15º of Sky Region, centered at that zenit, is coloured based on
the normalized count.

The contribution of all observers is then averaged providing a final picture with a spatial granularity of 5º by 5º of 
Sky Region. In summary, the Radio Meteor Activity Projection program produces a “couloured representation of the Meteor 
Activity Projection over a Star Chart" or "SkyMAP", assigning a colour, which is directly proportional to the average
of the normalized contribution of all observers counts.

-------------------
Running the program
-------------------

For running the software you will need to make available to the program a Java Virtual Machine 1.7 or greater.

Unzip the program file into a directory.

If you have installed Java 1.7 or later version, a double click on the RMAP.jar should start the program 
(be patient, it could take some time, depending on the machine)

------------
Troubleshoot
------------

If the program does not start, try to execute the program from a Terminal window.

>java -jar RMAP.jar

If you want to find out the current version of Java. Open a Terminal and type:

>java -version

Example: If you have a version 1.7 installed in the directory "/home/my_user/jvm/j1.7", you can open a Terminal
window, go to the directory where the RMAP program is installed and type:

>/home/my_user/jvm/j1.7/bin/java -jar ./RMAP.jar

-----------
QUICK START
-----------

  1. Let the computer get access to the Internet.

  2. Click on 'Real Time' in the Bar Menu.

  3. Click on 'Start' option.

The program will connect to the RMOB web site and download the RMOB files into the computer. After that, the program
will process the downloaded files and generate a SkyMAP picture.
 
------------------------
PROCESS OF ARCHIVED DATA
------------------------

  1. Get the RMOB Survey files from the RMOB web site main page:

    1.1. http://www.rmob.org/index.php
    1.2. [Click on...] Download
    1.3. [Click on...] RMOB Tools
    1.4. [Click on...] RMOB Survey Files for the Year [YYYY]

    Click on the link of the desired year, and a window will be opened.

    Then, click on the Floppy Disk Icon and the download will automatically be started.

  2. Unzip the RMOB Survey file in a desired folder, preferibly, empty.

  3. In the menu bar of the program click on : File -> Process Selected RMOB Files

  4. Select one or more RMOB files.

  5. For every RMOB file that contains the characters "rmob.TXT" or "rmob.txt", and that comply with several conditions
     of integrity, the program will generate a file begining with the same name, but ending in "_DB.txt".

  6. Introduce the year, of the RMOB Survey file selected, in the Year Box at the botton of the program window.

  7. In the menu bar of the program click on: File -> Process Directory of DB Files

  8. Select the directory of the DB files recently created.

  9. A process of DB files will start, and depending on the inputs in the boxes of Month - Day - Hour - Period - Records,
  a SkyMAP picture will be generated. If any change on those boxes is done, click on Process button to apply the change
  and get an updated SkyMAP picture.

-------------------
Program Description
-------------------

The Menu Bar is composed by the following items:

  * File
  * Image
  * Logging
  * Real Time
  * Help

----
File
----

There are three kind of files treated by the Radio Meteor Projection software:

  * the Radio Meteor Observation Bulletin Survey (RMOB) files, 
  * the Data Base (DB) files, and 
  * the SkyMAP files.

The items, in the File Menu, to process these file types are:

  * Process RMOB Files
  * Process DB Files
  * Save SKM File
  * Load SKM File

------------------
Process RMOB Files
------------------

The data format presented in RMOB Survey files is a time based format. The sample data content is composed by a matrix
of hours (horizontal) versus days (vertical). A meteor reflection count for every UTC hour of a given day is provided.

The following is an example of December 2009 register recorded by Chris Steyaert:

dec| 00h| 01h| 02h| 03h| 04h| 05h| 06h| 07h| 08h| 09h| 10h| 11h| 12h| 13h| 14h| 15h| 16h| 17h| 18h| 19h| 20h| 21h| 22h| 23h|
 01| 59 | 60 | 56 | 62 | 58 | 51 | 51 | 47 | 49 | 41 | 45 | 32 | 33 | 30 | 22 | 28 | 17 | 25 | 19 | 20 | 35 | 48 | 38 | 45 |
 02| 44 | 48 | 51 | 60 | 50 | 50 | 43 | 49 | 38 | 56 | 43 | 41 | 35 | 29 | 28 | 32 | 22 | 22 | 27 | 21 | 37 | 47 | 41 | 39 |
 03| 54 | 63 | 71 | 62 | 61 | 65 | 56 | 42 | 48 | 33 | 32 | 40 | 37 | 31 | 30 | 23 | 14 | 11 | 23 | 25 | 30 | 41 | 33 | 54 |
 04| 55 | 58 | 54 | 53 | 50 | 45 | 58 | 61 | 41 | 37 | 31 | 34 | 32 | 32 | 21 | 21 | 21 | 27 | 35 | 32 | 46 | 51 | 35 | 37 |
 05| 49 | 59 | 49 | 63 | 58 | 61 | 53 | 54 | 48 | 42 | 25 | 28 | 20 | 27 | 34 | 22 | 15 | 19 | 14 | 22 | 38 | 38 | 41 | 45 |
 06| 48 | 60 | 47 | 53 | 52 | 68 | 66 | 55 | 49 | 36 | 29 | 29 | 34 | 29 | 32 | 26 | 20 | 22 | 27 | 36 | 39 | 41 | 52 | 55 |
 07| 63 | 58 | 59 | 59 | 61 | 50 | 50 | 46 | 55 | 51 | 27 | 44 | 20 | 34 | 29 | 17 | 24 | 20 | 24 | 23 | 36 | 48 | 56 | 59 |
 08| 65 | 62 | 56 | 73 | 67 | 67 | 66 | 59 | 62 | 65 | 45 | 53 | 40 | 38 | 30 | 26 | 23 | 23 | 25 | 34 | 45 | 45 | 45 | 54 |
 09| 63 | 63 | 65 | 56 | 67 | 53 | 42 | 54 | 67 | 47 | 32 | 36 | 42 | 29 | 28 | 25 | 33 | 18 | 37 | 36 | 31 | 54 | 49 | 48 |
 10| 64 | 56 | 56 | 57 | 69 | 74 | 56 | 56 | 48 | 52 | 43 | 41 | 41 | 33 | 23 | 28 | 27 | 24 | 24 | 42 | 49 | 55 | 61 | 64 |
 11| 71 | 69 | 75 | 84 | 68 | 89 | 84 | 71 | 80 | 74 | 50 | 35 | 32 | 35 | 36 | 29 | 32 | 33 | 29 | 33 | 54 | 57 | 85 | 76 |
 12|119 | 62 | 55 | 77 | 87 | 91 | 92 |108 | 59 | 47 | 45 | 41 | 27 | 26 | 29 | 26 | 15 | 33 | 38 | 49 | 63 | 79 | 76 |134 |
 13|131 |117 |105 |103 |128 |101 |120 |114 |110 |112 | 44 | 42 | 34 | 42 | 50 | 29 | 26 | 46 | 64 | 73 |119 |130 |151 |200 |
 14|217 |192 |142 |147 |162 |121 |124 |110 |124 |123 | 92 | 66 | 53 | 43 | 29 | 28 | 33 | 31 | 37 | 46 | 63 | 70 | 90 | 69 |
 15|117 |100 |110 | 84 | 90 | 76 | 75 | 72 | 71 | 67 | 55 | 62 | 48 | 35 | 36 | 38 | 44 | 28 | 34 | 29 | 51 | 52 | 55 | 50 |
 16| 61 | 56 | 62 | 66 | 53 | 66 | 65 | 59 |??? |??? |??? |??? | 61 | 61 | 44 | 32 | 30 | 25 | 26 | 35 | 32 | 35 | 41 | 50 |
 17| 61 | 59 | 72 | 70 | 59 | 72 | 61 | 63 | 57 | 51 | 49 | 43 | 49 | 37 | 46 | 38 | 25 | 37 | 40 | 26 | 52 | 58 | 63 | 63 |
 18| 58 | 66 | 70 | 56 | 67 | 66 | 54 | 47 | 47 | 44 | 36 | 37 | 24 | 29 | 36 | 25 | 28 | 25 | 28 | 43 | 38 | 48 | 43 | 43 |
 19| 70 | 71 | 67 | 71 | 75 | 67 | 70 | 74 | 65 | 56 | 32 | 32 | 23 | 36 | 28 | 13 | 33 | 32 | 23 | 40 | 46 | 43 | 47 | 34 |
 20| 43 | 50 | 60 | 62 | 61 | 72 | 68 | 78 | 61 | 57 | 31 | 29 | 34 | 32 | 44 | 34 | 28 | 34 | 40 | 30 | 43 | 46 | 55 | 39 |
 21| 70 | 78 | 71 | 65 | 63 | 73 | 75 | 86 | 74 | 52 | 42 | 47 | 41 | 49 | 46 | 35 | 32 | 32 | 37 | 30 | 42 | 50 | 59 | 63 |
 22| 64 | 67 | 66 | 63 | 78 | 88 | 89 | 72 | 79 | 85 | 72 | 61 | 55 | 41 | 44 | 35 | 30 | 34 | 25 | 34 | 27 | 44 | 30 | 43 |
 23| 61 | 70 | 56 | 75 | 79 | 56 | 62 | 62 | 67 | 49 | 48 | 37 | 34 | 35 | 28 | 23 | 25 | 21 | 25 | 37 | 35 | 41 | 38 | 32 |
 24| 49 | 55 | 48 | 60 | 58 | 55 | 55 | 40 | 46 | 38 | 31 | 32 | 27 | 29 | 27 | 22 | 28 | 19 | 32 | 41 | 41 | 37 | 49 | 56 |
 25| 59 | 57 | 58 | 56 | 70 | 67 | 52 | 52 | 35 | 33 | 32 | 37 | 36 | 46 | 38 | 39 | 32 | 35 | 33 | 30 | 40 | 51 | 41 | 55 |
 26| 43 | 51 | 52 | 71 | 60 | 68 | 51 | 54 | 59 | 31 | 39 | 39 | 30 | 36 | 19 | 21 | 18 | 34 | 25 | 29 | 32 | 51 | 37 | 41 |
 27| 42 | 69 | 76 | 80 | 68 | 74 | 62 | 61 | 57 | 40 | 33 | 38 | 24 | 39 | 33 | 27 | 31 | 20 | 29 | 37 | 39 | 43 | 45 | 29 |
 28| 54 | 73 | 62 | 57 | 70 | 62 | 69 | 53 | 52 | 36 | 38 | 43 | 30 | 42 | 31 | 23 | 22 | 29 | 18 | 21 | 45 | 42 | 47 | 41 |
 29| 56 | 56 | 67 | 65 | 76 | 74 | 63 | 59 | 38 | 34 | 41 | 39 | 43 | 43 | 45 | 46 | 33 | 39 | 30 | 28 | 31 | 43 | 36 | 31 |
 30| 44 | 60 | 54 | 55 | 64 | 60 | 51 | 46 | 42 | 34 | 29 | 25 | 35 | 45 | 60 | 41 | 36 | 42 | 36 | 28 | 38 | 41 | 44 | 49 |
 31| 58 | 46 | 57 | 58 | 65 | 68 | 61 | 70 | 55 | 49 | 29 | 36 | 38 | 29 | 38 | 19 | 27 | 22 | 24 | 21 | 44 | 52 | 53 | 35 |

RMOB files are processed to extract the counting information and to generate the DB files. The DB files are basically
composed by normalized counts got from the RMOB files, and associated to a position in the sky, given by the Rigth 
Ascension and Declination of the Observer's zenit at the UTC time of the count.

The menu option let us to select one or more files in a directory.

----------------
Process DB Files
----------------

This process work in an entire directory. Therefore, when selecting a DB file in a directory, all DB files in that
directory will be included in the process.

This process work together with a set of conditions that have to be stated in the boxes located at the botton of the main
window. As shown in the next example, these boxes are found in the following order:

 ------------------------------------------------------------------------------
| Year: 2013 | Month:01 | Day:01 | Hour:00 | Shift: 1 | Period:24 | Records:48 |
 ------------------------------------------------------------------------------

The DB files are essentially, a set of lines containing, at least, a UTC Date/Time, a Normalized Count (Relative Estimation),
a Right Ascension and a Declination figures.

The DB Process consist of reading every line of each DB file, looking for a match between the UTC Date/Time and the
criteria stated in the abovementioned boxes (Year/Month/Day/Hour/Shift/Period).

When a match is found, the normalized count is added to the position in the sky given by the Right Ascension and 
Declination figures, and considering a range of 15 degrees in both axis. 

In the previous example, if we select a directory of DB files for processing, the program will open every DB file looking
for a date like 20130101 (1st Jan 2013) at 00h, 01h, ..., 23h hours (period of 24 hours), for the first record, then
it will increment in 1 hour the time (Shift), and select from 1st Jan 2013 at 01h to 2nd Jan 2013 at 00h for the second
record, then it will increment in 1 hour again the time, and select from the 1st Jan 2013 at 02h to 2nd Jan 2013 01h, and 
so on, until the last record is generated.

The set of records generated is as follows:

---------------
YYYYMMDDHHMMSS |
---------------
20130101003000 | Record 1
20130101013000 |
...            |
20130101233000 |
---------------
20130101013000 | Record 2
20130101023000 |
...            |
20130102003000 |
---------------
...
---------------
20130102233000 | Record 48
20130103003000 |
...            |
20130103223000 |
---------------

That is, the program will generate 48 records, and each record is a SkyMAP containing the contribution of all observers
in the directory, for a period of 24 hours, with a difference of one hour between one record and the next one. Each record 
is shifted an amount of time indicated by the "Shift" field.

If the Year Box is leave it in blank, all the data matching Month/Day/Time is used to contribute to the SkyMAP records,
in that way, data from different years for the same month are compiled together.

If a directory for DB processing has already been selected, after any change in the boxes of Year, Month, etc. can be 
applied clicking on the Process button. 

----------------
Save SkyMAP File
----------------

For some queries over the DB files, it is possible that generation of SkyMAP records take a while. If we desire to store
the SkyMAP records in a SkyMAP file, we can select this option, and recover later the SkyMAP, without having to extract
it again from the DB files.

----------------
Load SkyMAP File
----------------

Option for recovering the SkyMAP files stored on the disk.

-----
Image
-----

* Toogle Projection
* Change point of View
* Toogle Palette
* Toogle Sky Color
* Stars
* Constellations
* Streams
* Grid
* Sites
* Loop

-----------------
Toogle Projection
-----------------

There are two kind of projections, a cartesian projection and an elliptical-like projection.

--------------------
Change Point of View
--------------------

This option let to change the point of view of an observer watching the sky. The default value is as if the sky is observed
from the Earth's surface. If we select to change, the point of view is moved to a point behind the stars.

--------------
Toogle Palette
--------------

There are three Palettes for preseting the Meteor Activity. By default, the Meteor Activity is presented in a color scale,
where the red indicates greater activity and the blue indicates less activity, and in the middle there is a variable color
passing by green, yellow and oranges.

Another option is a dual color from red for greater activity to blue for less activity.

And the third option is another dual color from red for greater activity to black for less activity.

----------------
Toogle Sky Color
----------------

This option let us change the color of the Sky. By default, is white, with the stars plotted in black. The second option is
to present the sky in black, with the stars plotted in white.


----------------
Stars
----------------

Hide/Show the stars.

----------------
Constellations
----------------

Hide/Show the constellations.

----------------
Streams
----------------

Hide/Show the streams.

Those streams are configured in the streams.cfg file with the following format:

#Name;     Day/Month Ini;  Day/Month End;  Day/Month Max;  RA(hours);  Dec(Degrees)
Geminids;  07/12;          17/12;          14/12;          7.47;       33

When the "Init Date" or "End Date" are included within the dates of the SkyMAP records being presented, a symbol presenting
that particular stream is drawn in the location given by RA and Dec. 

----
Grid
----

This option let us to remove or to replace the grid.

-----
Sites
-----

This option let us to remove or to draw the sites which are configured in the sites.cfg file. 

The sites, expressed in a single line, has three parts: Site Name, Latitude and Longitude.

Example:
Gran Canaria;28.022;-15.516

The program will draw a symbol on the Sky based on the Site Location and the UTC time of the current SkyMAP record.
If we want that a site is not drawn, but we want to keep the site location on the file, we can use the symbol # for
disabling the site drawing.

----
Loop
----

The Loop option increase, the loaded SkyMAP picture, in one record every second, that is, if the SkyMAP has 24 records,
the Loop option will present the 24 hour records one at a time, with a one second separation. In the rmap.cfg file, the
interval in miliseconds, set by default to 1000, can be varied to a desired miliseconds pause betwen records. 

-------
Logging
-------

The Logging menu is composed by two items:
* Log
* SkyMAP Data → Log

---
Log
---

The Logging Menu let us to open the Log of the RMAP application. When we are not sure if a process has given us the 
expected result, it would be interesting to have a look at the Log to see if something was wrong.

-----------------
SkyMAP Data → Log
-----------------
There is an option that let us to represent in text, through the Log window, the numeric content of a SkyMAP.
It has to be taken into account that in the SkyMAP matrixes, the first column on the left side represents 0 hours of RA.
That is, in that plain text representation, the Right Ascension increases from left to right . 

---------
Real Time
---------

-----
Start
-----

Start the real time process which consist of the automatic downloading and processing of the RMOB files.

----
Stop
----

Stop the real time process.

-----------------
SkyMAP Navigation
-----------------

Above the SkyMAP picture we can find the following buttons and boxes:

 -----------------------------------------------------------------------------------------------------------
| <- | Record | -> | #Obs >= |  1  | Intensity | Down | 1.0 | Up | -- PROGRESS BAR -- | Relative Estimation |     
 -----------------------------------------------------------------------------------------------------------

The buttons "<-" and "->" let us to decrease or increase, respectively, the SkyMAP record among all the records generated.

The #Obs let us to indicate the minimun number of observers contributing to the SkyMAP. When updating the number of
observers, click on "<-" or "->" to refresh the SkyMAP picture.

The intensity Down and Up buttons, let us to decrease or increase the color intensity of the SkyMAP.

The Progress Bar will report us about the progress in processing the RMOB or DB files.

The last combo box let us to select between Estimation and Relative Estimation. The difference is that "Estimation" is
the direct measurement of the count got from the observers, and the "Relative Estimation" is a ponderation of the 
observer's count using the own observer's count average.

-------------------
Configuration Files
-------------------

------------
DB_Files.cfg
------------

When the realtime option is selected, a file called "DB_Files.cfg", with the file names downloaded is created/updated. 
If we want to disable the processing of a particular file, we have to set a "0" at the beginning of the line before the 
file name. 

#Valid(1:Yes / 0:No);File Name
1;Booth_122013rmob_DB.txt




						  Copyright (c) - 2013 - Esteban Holgado N.
						               estbhan@gmail.com
						             Gran Canaria  -  Spain
