This page describes how RTML requests are mapped into the scheduler database. Before continuing, be sure you are familiar with the request data hierarchy in the scheduler and the object model for the RTML 2.3 schema, as implemented by this engine.
The following basic mappings are provided by the scheduler RTML importer:
RTML | Scheduler |
---|---|
Request | Plan |
Target | Observation |
Picture | ImageSet |
This section describes the mapping from an RTML Request to a scheduler Plan. An RTML document may contain multiple Requests and thus may produce multiple scheduler Plans.
Each RTML Request must contain a UserName field. If it matches the name of an Observer in the scheduler database, the Plan is created for that Observer. If not, a new Observer is created with the given RTML UserName.
Each RTML Request is checked for a Project field. If it exists, and if there is a Project in the scheduler for the Observer (as determined above), the new Plan will be added to that Project. Otherwise a new Project whose name will be of the form yyyy-mm-dd UTC will be created and the new Plan will be added to it. Note that this action takes place for each RTML Request in the RTML document (there may be more than one).
If a new Project is created, its description will be set to "Project created from imported RTML". In addition the new Project's Contact Name, Email, Organization, and Observers will be set from the corresponding RTML Contact and Request fields, if present in the RTML.
Special feature for ACP web users: If the RTML's Contact User field ends with " [ACP xxxxx]" (note the leading space), where xxxxx is an ACP web login username (not the friendly name), the Scheduler will, by default, store images and logs resulting from observations in the ACP web-visible directories for that ACP user. See Custom Image File and Folder Naming and the information in ImageFileConfig.txt. Feel free to contact DC-3 Dreams for additional information.
Each RTML Request is checked for an ID field. If it exists, the Request's ID field is used as the name for the Plan. If not, the Plan is named "Request n", where n is the sequence number of the Request in the RTML document.
To force the dispatcher to start a Plan at a specific time, include a TimeRange element in the Request and set its Earliest and Latest child elements to identical date/time values. This will cause the "fixed-time" flag to be set for the Plan. Fixed-time plans are always started before any other plans, and are thus guaranteed to run. Observations belonging to fixed-time plans may preempt those belonging to other Observations of Plans started before a fixed-time plan is added.
The Request.TimeRange has a special feature for time-critical plans. If both the Earliest and Latest are set to 0001-01-01T00:00:00 the plan will be started immediately.
RTML 2.3 doesn't support Scheduler's Monitor Mode, however you can still enable it on a Plan created from imported RTML. To enable Monitor Mode for a Plan (which results from an RTML Request), put Monitor=n into the Request's Reason attribute, where n is the monitor interval in days.
RTML | Scheduler |
---|---|
Request.Schedule.Priority | Plan.BasePriority |
Request.Description | Plan.Description |
Request.bestefforts (attrib) | Plan.BestEfforts |
Request.Schedule.TimeRange.Earliest | Plan.Earliest |
Request.Schedule.TimeRange.Latest | Plan.Latest |
Request.TimeStamp | Plan.TimeStamp |
This section describes the mapping from an RTML Target to a scheduler Observation. Each RTML Request may contain multiple Targets and thus may result in a Plan with multiple Observations.
Each RTML Target must contain a Name field. This name is used as the name for the corresponding Observation. The name may have a sequence number appended if the import results in multiple Observations for the Target (see below).
The RTML Target is checked for a Description field. If it exists, it is used for the Description field of the Observation. If not, the Target is checked for an ID field. If that exists the Description will be set to "RTML Target ID: ID". Otherwise the Description is set to "RTML Target".
If the RTML Target specifies the autofocus attribute to be True, then the Autofocus option will be turned on for the corresponding scheduler Observation. The system will perform an autofocus before acquiring images for the target.
RTML 2.3 supports the three target coordinate types supported by scheduler. Only one type may be legally present in an RTML document:
RTML | Scheduler |
---|---|
Target.Coordinates | RA and Dec |
Target.OrbitalElements | Orbital Elements |
Target.Planet | Major Planet |
RightAscension in RTML is in degrees not hours
In addition, all three coordinate types support equatorial position angle for rotators, and this is taken from RTML's Target.PositionAngle.
If an RTML Target specifies a count attribute with a value greater than 1, it means that the Target must be repeated, and thus the scheduler must repeat the corresponding Observation. There are three ways that the RTML importer deals with this:
If the Target has a count attribute greater than 1 and no interval attribute or interval = 0, then count becomes the Observation's repeat count and a single observation is generated with that repeat count.
If the Target has a count attribute greater than 1 and an interval greater than 0, multiple Observations are generated, with the second and subsequent Observations' Time From Previous set to the interval and Timing Tolerance set to 15% of the interval.
If the Target has a count attribute greater than 1, an interval greater than 0, and a tolerance greater than 0, multiple Observations are generated, with the second and subsequent Observations' Time From Previous set to the interval and Timing Tolerance set to tolerance.
The interval and tolerance values in RTML are in hours.
The interval is the time spacing from the start of the previous observation to the start of the current one. If you specify too short an interval, the scheduler will fail the Plan because the Observation will have missed its timing.
Historically, RTML specified its constraints in the Request.Schedule section. While this limits the flexibility of RTML as applied to the scheduler (which can have separate constraints for each Observation), it preserves backward compatibility with older versions of RTML. Each Target (which maps to an Observation) carries the same constraints, derived from the Request.Schedule fields. The names of the constraints in Request.Schedule are the same as the standard scheduler constraints.
If an RTML Request has multiple Target fields, additional Observations will be added to the parent Plan. The timing between these Observations and previous ones is determined by the Target attributes timefromprev and tolfromprev. If neither are specified, the first Observation generated by the second and subsequent Target will be specified with Immediately After Previous. If timefromprev is specified and is greater than 0, tolfromprev must also be specified and must also be greater than 0. In this case, the first Observation generated will be spaced in time from the start of the previous one by timefromprev, with a tolerance of tolfromprev. This is analogous to using the interval and tolerance fields for a Target with count greater than 0.
If the above seems confusing, it's suggested that you make up some RTML test documents and play with it. Eventually you'll understand. You can also ask for assistance on the DC-3 Dreams Comm Center.
The mapping between an RTML Picture element and a scheduler ImageSet is straightforward:
RTML | Scheduler |
---|---|
Picture.Name | ImageSet.Name |
Picture.Description | ImageSet.Description |
Picture.count (attrib) | ImageSet.Count |
Picture.ExposureTime | ImageSet.ExposureInterval |
Picture.Binning | ImageSet.Binning |
Picture.Filter | ImageSet.Filter |
Picture.autostack (attrib) | ImageSet.AutoStack |
Historically, RTML specified individual calibration request(s) in the Request.Correction section. While this limits the flexibility of RTML as applied to the scheduler (which can have separate calibration steps for each ImageSet), it preserves backward compatibility with older versions of RTML. The following shows the Correction fields as mapped to scheduler calibration steps in ImageSet.
NOTE: For ACP Scheduler 3.7 and later, the individual calibration steps are deprecated. If any of zero, dark, or flat are set, a full automatic calibration will be performed with MaxIm DL's calibration wizard. If fixpix is set, a hot pixel removal will be done after calibration. If none of the first three are set (no calibration) the hot pixel removel will not be done.
RTML | Scheduler |
---|---|
Correction.zero (attrib) | ImageSet.Bias |
Correction.dark (attrib) | ImageSet.Dark |
Correction.flat (attrib) | ImageSet.Flat |
Correction.fixpix (attrib) | ImageSet.HotPix |