diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 4ba3e2b..afc2817 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,7 +1,7 @@ name: Check the IVOA document env: - doc_name: ObjVisSAP + doc_name: ObjObsSAP on: pull_request: @@ -25,7 +25,7 @@ jobs: sudo apt install texlive-latex-base texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended xsltproc latexmk cm-super - name: Build the document - run: make + run: make biblio forcetex - name: Check the output run: | @@ -33,7 +33,7 @@ jobs: test -f ${{ env.doc_name }}.bbl - name: Keep the PDF artefact - uses: actions/upload-artifact@v1 + uses: actions/upload-artifact@v4 with: name: PDF Preview path: ${{ env.doc_name }}.pdf diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index 60d2471..e565ee7 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -1,7 +1,7 @@ name: Update PDF Preview env: - doc_name: ObjVisSAP + doc_name: ObjObsSAP on: push: @@ -27,7 +27,7 @@ jobs: sudo snap install pdftk - name: Build the document - run: make ${{ env.doc_name }}-draft.pdf + run: make biblio ${{ env.doc_name }}-draft.pdf - name: Check the output run: | @@ -35,10 +35,10 @@ jobs: test -f ${{ env.doc_name }}.bbl - name: Move the auto-pdf-preview tag - uses: weareyipyip/walking-tag-action@v1 + uses: weareyipyip/walking-tag-action@v2 with: - TAG_NAME: auto-pdf-preview - TAG_MESSAGE: | + tag-name: auto-pdf-preview + tag-message: | Last commit taken into account for the automatically updated PDF preview of this IVOA document. env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index afed28c..e400f95 100644 --- a/.gitignore +++ b/.gitignore @@ -5,8 +5,9 @@ **/*.dvi **/*.log **/*.out -**/ObsLocTAP.synctex.gz -**/ObsLocTAP.ps -**/ObsLocTAP.pdf -**/ObsLocTAP.fls -**/ObsLocTAP.fdb_latexmk +**/ObjObsSAP.synctex.gz +**/ObjObsSAP.ps +**/ObjObsSAP.pdf +**/ObjObsSAP.fls +**/ObjObsSAP.fdb_latexmk +**/ObjObsSAP.toc diff --git a/Makefile b/Makefile index 2ef5eb5..7efe72b 100644 --- a/Makefile +++ b/Makefile @@ -1,20 +1,20 @@ # ivoatex Makefile. The ivoatex/README for the targets available. # short name of your document (edit $DOCNAME.tex; would be like RegTAP) -DOCNAME = ObjVisSAP +DOCNAME = ObjObsSAP # count up; you probably do not want to bother with versions <1.0 DOCVERSION = 1.0 # Publication date, ISO format; update manually for "releases" -DOCDATE = 2020-09-30 +DOCDATE = 2024-11-18 # What is it you're writing: NOTE, WD, PR, REC, PEN, or EN DOCTYPE = WD # An e-mail address of the person doing the submission to the document # repository (can be empty until a make upload is being made) -AUTHOR_EMAIL=jesusjuansalgado@gmail.com +AUTHOR_EMAIL=aitor.ibarra@ext.esa.int # Source files for the TeX document (but the main file must always # be called $(DOCNAME).tex diff --git a/ObjVisSAP.tex b/ObjObsSAP.tex similarity index 78% rename from ObjVisSAP.tex rename to ObjObsSAP.tex index 1f9114d..eea2263 100644 --- a/ObjVisSAP.tex +++ b/ObjObsSAP.tex @@ -13,7 +13,8 @@ \usepackage{adjustbox} \usepackage{lscape} \usepackage[title]{appendix} - +\usepackage{tabularx} +\newcolumntype{L}{>{\raggedright\arraybackslash}X} \usepackage[english]{babel} %Import the natbib package and sets a bibliography and citation styles @@ -38,7 +39,7 @@ \begin{html}#1\end{html}} \customcss{custom.css} -\title{Object Visibility Simple Access Protocol} +\title{Object Observability Simple Access Protocol} \ivoagroup{Data Access Layer Group} @@ -77,20 +78,20 @@ \begin{document} \begin{abstract} -The Object Visibility Simple Access Protocol (ObjVisSAP) is an IVOA Data +The Object Observability Simple Access Protocol (ObjObsSAP) is an IVOA Data Access protocol which defines the standard for retrieving object -constraint-free visibility time intervals through a uniform interface within +constraint-free observability time intervals through a uniform interface within the VO framework for given object coordinates to be observed by a given -Astronomical Observatory. The ObjVisSAP services can be registered in an +Astronomical Observatory. The ObjObsSAP services can be registered in an IVOA Registry of Resources using the VOResource, Extension standard, having -a unique ResourceIdentifier in the registry. The ObjVisSAP interface is +a unique ResourceIdentifier in the registry. The ObjObsSAP interface is meant to be reasonably simple to be implemented by service providers. A basic query will be done introducing a set of sky coordinates and a given time period (optional). The service returns a list of constraint-free -visibility time intervals formatted as VOTable. Thus, an implementation of +observability time intervals formatted as VOTable. Thus, an implementation of the service may support additional search parameters (some of which may be custom to that particular service) to more finely control the selection of -the visibility periods. The specification also describes how the search on +the observability periods. The specification also describes how the search on extra parameters has to be done. \end{abstract} @@ -114,7 +115,7 @@ \section*{Conformance-related definitions} infrastructure that enable VO applications. \section*{Link to IVOA Architecture} -The figure below shows where ObjVisSAP protocol fits within the +The figure below shows where ObjObsSAP protocol fits within the IVOA architecture: %%%%%%%%%%%%%%%%%%%% Figure/Image No: 1 starts here %%%%%%%%%%%%%%%%%%%% @@ -133,17 +134,17 @@ \section*{Link to IVOA Architecture} \section{Introduction}\label{section:_Toc415497365} -The Object Visibility Simple Access Protocol (ObjVisSAP henceforth) +The Object Observability Simple Access Protocol (ObjObsSAP henceforth) specifies in a standard format the services to retrieve object -visibility from astronomical observatories. +observability from astronomical observatories. -The ObjVisSAP interface has intentionally been made similar to the SSAP +The ObjObsSAP interface has intentionally been made similar to the SSAP \citep{2012ivoa.spec.0210T} and SIAP v2.0 \citep{2015ivoa.spec.0617D} through the adoption of current IVOA Data Access Layer Interface (DALI; \citealt{2017ivoa.spec.0517D}) and Observation Data Model Core Components (ObsCore;\citealt{2017ivoa.spec.0509L}) and its implementation in -the Table Access Protocol (TAP;\citealt{2019ivoa.spec.0927D}). ObjVisSAP services also support +the Table Access Protocol (TAP;\citealt{2019ivoa.spec.0927D}). ObjObsSAP services also support VOSI-availability and VOSI-capabilities resources (VOSI;\citealt{2017ivoa.spec.0524G}): @@ -157,17 +158,17 @@ \section{Introduction}\label{section:_Toc415497365} \subsection{The Role in the IVOA Architecture} -ObjVisSAP specifies standardID values \citep{2016ivoa.spec.0523D} for each -capability, as defined by VODataService \citep{2010ivoa.spec.1202P}. ObjVisSAP +ObjObsSAP specifies standardID values \citep{2016ivoa.spec.0523D} for each +capability, as defined by VODataService \citep{2010ivoa.spec.1202P}. ObjObsSAP services may be registered in an IVOA Registry using the SimpleDALRegExt \citep{2017ivoa.spec.0530P} extension schema. \section{Requirements for Compliance} -The object visibility query web method \textbf{MUST} be supported as described -in section \ref{sec:query}. Through this web method, clients search for visibility +The object observability query web method \textbf{MUST} be supported as described +in section \ref{sec:query}. Through this web method, clients search for observability periods based on given sky coordinates and a time period (optional). The -response is a VOTable that describes the constraint-free visibility time +response is a VOTable that describes the constraint-free observability time windows. Other output formats can be specified by the RESPONSEFORMAT parameter (see \citet{2017ivoa.spec.0517D}). @@ -186,19 +187,18 @@ \subsection{Compliance} its protocols is said to be "conditionally compliant". \section{Resources} -The purpose of the object visibility query is to allow users/clients to -check if a given set of sky coordinates are visible for a given time -period. We define "visible" as the time interval suitable to perform -scientific observations. We therefore, leave to the observatories to -define when exactly an object is visible for scientific observations. +The purpose of the object observability query is to enable users and clients to +determine if a given set of sky coordinates is observable during a specified time period. +Here, "observable" refers to a time interval suitable for conducting scientific observations. +The precise definition of when an object is deemed observable for scientific purposes is therefore left to the individual observatories. The most basic query parameters will be the sky coordinates (Right Ascension and Declination), both coordinates must be expressed following the ICRS coordinate system and the start time and stop time for the -visibility checks (optional). Any additional parameters may be used to -customize the visibility checks. +observability checks (optional). Any additional parameters may be used to +customize the observability checks. -The ObjVisSAP service have been designed to follow the DALI-sync +The ObjObsSAP service have been designed to follow the DALI-sync specification. \begin{table}[h] @@ -217,9 +217,9 @@ \section{Resources} VOSI-capabilities & /capabilities & yes \\ \hline \end{tabular} -\caption{ObjVisSAP service resources} +\caption{ObjObsSAP service resources} \end{table} -The ObjVisSAP service must have at least one \{query\} resource. +The ObjObsSAP service must have at least one \{query\} resource. \subsection{\{query\} resource} \label{sec:query} The \{query\} resource is a synchronous web service resource that @@ -231,7 +231,7 @@ \subsection{\{query\} resource} \label{sec:query} As a DALI-sync resource, the parameters for a request may be submitted using an HTTP GET (query string) or POST action. -Object Visibility services advertise their availability as described in +Object observability services advertise their availability as described in the DALI standard. This system must provide mechanisms to fully characterize the service, including its non-compulsory and additional parameters. @@ -256,7 +256,7 @@ \subsection{\{query\} resource} \label{sec:query} names refer to those defined in the ObsCore Data Model . Some of the parameters proposed in this standard are not described in -the ObsCore Data Model document , such as; min\_vis, max\_vis, +the ObsCore Data Model document , such as; min\_obs, max\_obs, elevation, moon\_sep. We tried to describe these parameters following the ObsCore standard. @@ -266,15 +266,15 @@ \subsubsection{Required parameters} raising an error, and the parameters must be properly used to constrain the query. -As described in this section, the only mandatory parameters are the -Right Ascension and Declination of the point in the sky to check for -constraint-free time intervals. In this case, the service will return -all possible time intervals where the point in the sky is visible. The -time span covered by each astronomical observatory will depend on the -characteristics of each scientific instrument. For example, time spam -covered by ground based optical telescopes will be larger than time spam -covered by Low Earth Orbit observatories, where the satellite orbital -elements changes frequently. +As described in this section, the only mandatory parameters are the Right +Ascension and Declination of the sky coordinates for checking constraint-free +time intervals. In this context, the service will return all possible time +intervals during which the sky coordinates are observable. The duration of +these intervals will depend on the characteristics of each scientific +instrument. For instance, ground-based optical telescopes typically cover +longer observation periods than Low Earth Orbit observatories, where +satellite orbital elements change frequently. + \begin{itemize} \item{\textbf{MAXREC}\\MAXREC parameter is defined in DALI and allows @@ -286,11 +286,11 @@ \subsubsection{Required parameters} respond with metadata-only (normal output document with no records).} \item{\textbf{UPLOAD}\\DALI UPLOAD parameter is not used by this version -of ObjVisSAP. The use case of uploading lists of coordinates is covered +of ObjObsSAP. The use case of uploading lists of coordinates is covered by the multiple-valued parameters values.} \item{\textbf{POS}\\The service \textbf{MUST }support the -\textbf{POS} parameter, to specify the position in the sky to check the visibility. +\textbf{POS} parameter, to specify the position in the sky to check the observability. The coordinate values are specified in list format (comma separated) with no embedded white space.\\ Example:\\ @@ -307,14 +307,14 @@ \subsubsection{Required parameters} \item{\textbf{TIME}\\The service \textbf{MUST} support the \textbf{TIME} parameter, to specify the time coverage in range-list form -to check for object visibility. The unit of \textbf{TIME} parameter must be +to check for object observability. The unit of \textbf{TIME} parameter must be expressed in MJD. The format of the range list is the one defined by other IVOA S*APs protocols like SSAP \citep{std:SSAP}, where the format of a range is defined by '$t_{min}\slash t_{max}$'. If the range is defined as an open range without the lower value of the range like '$\slash t_{max}$', $t_{min}$ will be interpreted as now.\\ -\textbf{Example:} to query for object visibility of the coordinate +\textbf{Example:} to query for object observability of the coordinate (10.68,41,27) and end time for the periods between 11-April-2021 and 14-April-2021: %%%%%%%%%%%%%%%%%%%% starts here %%%%%%%%%%%%%%%%%%%% @@ -323,7 +323,7 @@ \subsubsection{Required parameters} \begin{tabular}{|l|l|} \hline \begin{lstlisting}[language=SQL] -http://xmmvischeck.esac.esa.int:8080/objvissap/query? +http://xmmvischeck.esac.esa.int:8080/objobssap/query? POS=10.68,41.27&TIME=59522/59532 \end{lstlisting} \\ @@ -332,7 +332,7 @@ \subsubsection{Required parameters} \end{table} %%%%%%%%%%%%%%%%%%%% ends here %%%%%%%%%%%%%%%%%%%% -Calculation of the visibility by different observatories is only defined +Calculation of the observability by different observatories is only defined for a certain future time range. That implies that there could be \textbf{a maximum time hard limit} defined by the service that could be smaller than the maximum of the \textbf{TIME} period value invoked by @@ -355,26 +355,26 @@ \subsubsection{Non-compulsory Parameters} server side. These parameters should be treated as reserved keywords. \begin{itemize} -\item{\textbf{VIS\_MIN}\\A service \textbf{MAY} have a search parameter -called \textbf{VIS\_MIN}. This parameter would constrain the visibility -check to those time periods with at least the minimum visibility specified -in the parameter. The unit of \textbf{VIS\_MIN} parameters must be expressed +\item{\textbf{MIN\_OBS}\\A service \textbf{MAY} have a search parameter +called \textbf{MIN\_OBS}. This parameter would constrain the observability +check to those time periods with at least the minimum observability specified +in the parameter. The unit of \textbf{MIN\_OBS} parameters must be expressed in seconds.\par \textbf{Example:} The input parameter listing below from the Object -Visibility Simple Access Protocol shows that in addition to supporting +observability Simple Access Protocol shows that in addition to supporting the required parameters (POS, TIME), it also supports the free -parameter VIS\_MIN. +parameter MIN\_OBS. %%%%%%%%%%%%%%%%%%%% starts here %%%%%%%%%%%%%%%%%%%% \begin{lstlisting}[language=XML] +xmlns:ovdm="http://www.ivoa.net/xml/ObjectObservabilityDM/ +ObjectobservabilityDM-v1.0.xsd" version="1.0"> -Object Visibility Simple Access Protocol +Object Observability Simple Access Protocol Specify the time coverage (epoch), specified in range-list form -to check for visibility. To be specified in MJD. +to check for observability. To be specified in MJD. - - Minimum visibility interval interval + Minimum observability time interval ... ... ... ... @@ -406,25 +406,25 @@ \subsubsection{Non-compulsory Parameters} } \item{\textbf{FACILITY}\\A service \textbf{MAY} have a search parameter called \textbf{FACILITY}. This parameter would constrain the output of -visibility ranges for services with multiple telescopes/facilities. -This could be used, e.g., to select visibility ranges for telescopes +observability ranges for services with multiple telescopes/facilities. +This could be used, e.g., to select observability ranges for telescopes arrays, preventing the need of registration of one service per telescopes for this kind of observatories. Also, this could be useful for antennas arrays.} \end{itemize} \subsection{Availability: VOSI-availability} -A web service with ObjVisSAP capabilities \citep{2017ivoa.spec.0524G} must have a +A web service with ObjObsSAP capabilities \citep{2017ivoa.spec.0524G} must have a VOSI-availability resource as described in DALI \citep{2017ivoa.spec.0517D}. \subsection{Capabilities: VOSI-capabilities} -A web service with ObjVisSAP capabilities must have a VOSI-capabilities +A web service with ObjObsSAP capabilities must have a VOSI-capabilities resource as described in DALI. The standardID for the \{query\} capability is: %%%%%%%%%%%%%%%%%%%% starts here %%%%%%%%%%%%%%%%%%%% \begin{lstlisting}[language=SQL] -ivo://ivoa.net/std/ObjVisSAP#query-0.3 +ivo://ivoa.net/std/ObjObsSAP#query-0.3 \end{lstlisting} %%%%%%%%%%%%%%%%%%%% ends here %%%%%%%%%%%%%%%%%%%% All DAL services must implement the /\textit{capabilities} resource. @@ -441,21 +441,21 @@ \subsection{Capabilities: VOSI-capabilities} - http://example.com/ObjVisSAP/capabilities + http://example.com/ObjObsSAP/capabilities - http://example.com/ObjVisSAP/availability + http://example.com/ObjObsSAP/availability - + - http://example.com/ObjVisSAP/query + http://example.com/ObjObsSAP/query @@ -505,12 +505,12 @@ \subsection{Successful Query} Since the \{query\} response is usually dynamically generated, the Content-Length and Last-Modified headers cannot usually be set.\\ -The output returned by a ObjVisSAP service is a VOTable , an XML table +The output returned by a ObjObsSAP service is a VOTable , an XML table format, returned with a MIME-type of "application/x-votable+xml". The -table lists all the visibility periods computed for the given +table lists all the observability periods computed for the given coordinates and time period in the server. The following requirements are placed on the contents of the table when the query successfully -returns a list of visibility periods: +returns a list of observability periods: \newcounter{numberedCntBI} \begin{enumerate} @@ -522,7 +522,7 @@ \subsection{Successful Query} results be returned in the first resource element. \item The RESOURCE element \textbf{MUST} contains an INFO element with name="QUERY\_STATUS". Its value attribute should be set to "\,OK" if the -query executed successfully, regardless of whether any visibility period +query executed successfully, regardless of whether any observability period for the given coordinates were found. \setcounter{numberedCntBI}{\theenumi} \end{enumerate} @@ -538,11 +538,11 @@ \subsection{Successful Query} \begin{enumerate} \setcounter{enumi}{\thenumberedCntBI} -\item Each table row represents a different visibility period. +\item Each table row represents a different observability period. \item Each record of the output VOTable \textbf{MUST} contain value for each FIELD. \item Every FIELD \textbf{SHOULD} contain a utype reference to the -object visibility Data Model whenever possible. +object observability Data Model whenever possible. \item A standard column \textbf{MUST} have a defined utype and a defined UCD as described in next section \item A standard column could appear multiple times with different @@ -561,8 +561,8 @@ \subsection{Successful Query} %%%%%%%%%%%%%%%%%%%% starts here %%%%%%%%%%%%%%%%%%%% \begin{lstlisting}[language=XML] -xmlns:ovdm="http://www.ivoa.net/xml/ObjectVisibilityDM/ -ObjectVisibilityDM-v1.0.xsd" +xmlns:ovdm="http://www.ivoa.net/xml/ObjectObservabilityDM/ +ObjectObservabilityDM-v1.0.xsd" \end{lstlisting} %%%%%%%%%%%%%%%%%%%% ends here %%%%%%%%%%%%%%%%%%%% @@ -572,7 +572,7 @@ \subsubsection{Standard output fields} \begin{itemize} \item {Exactly one field \textbf{MUST} have a name="\textbf{t\_validity}" with\\ utype=" \textbf{Char.TimeAxis.Coverage.Time}" with -datatype="float", ucd="time.validity", unit="d" containing the date when the visibility calculations will change.} +datatype="float", ucd="time.validity", unit="d" containing the date when the observability calculations will change.} \item {Exactly one field \textbf{MAY} have a name="\textbf{validity\_accuracy}" with datatype="char" and arraysize="*" containing the level of @@ -581,19 +581,19 @@ \subsubsection{Standard output fields} \item {Exactly one field \textbf{MAY} have a name="\textbf{ validity\_predictor}" with datatype="char" and arraysize="*" with an -identifier of the software used to calculate the visibility.} +identifier of the software used to calculate the observability.} \item {Exactly one field \textbf{MUST} have a name="\textbf{t\_start}" with\\ utype="\textbf{Char.TimeAxis.Coverage.Bounds.Limits.StartTime}"\\ with -datatype="float", ucd="time.start", unit="d" containing the start of the visibility period.} +datatype="float", ucd="time.start", unit="d" containing the start of the observability period.} \item {Exactly one field \textbf{MUST} have a name="\textbf{t\_stop}" with\\ utype="\textbf{Char.TimeAxis.Coverage.Bounds.Limits.StopTime}"\\, with -datatype="float", ucd="time.end" and unit="d" containing the end of the visibility period.} +datatype="float", ucd="time.end" and unit="d" containing the end of the observability period.} -\item {Exactly one field \textbf{MUST} have a name="\textbf{t\_visibility}" +\item {Exactly one field \textbf{MUST} have a name="\textbf{t\_observability}" with\\ utype="\textbf{Char.TimeAxis.Coverage.Support.Extent}"\\, with -datatype="float", ucd="time.duration" and unit="s", containing the visibility window duration in seconds.} +datatype="float", ucd="time.duration" and unit="s", containing the observability window duration in seconds.} \item {Exactly one field \textbf{MAY }have a name="\textbf{pos\_angle }" with\\ @@ -603,42 +603,44 @@ \subsubsection{Standard output fields} \item {Exactly one field \textbf{MAY }have a name="\textbf{em\_min}" with\\ utype="\textbf{Char.Spectral.Axis.Energy.Min}"\\ -datatype="float", ucd="em.energy" and unit="m" , containing the low energy bound for this particular sky position and visibility time interval.} +datatype="float", ucd="em.energy" and unit="m" , containing the low energy bound for this particular sky position and observability time interval.} \item {Exactly one field \textbf{MAY }have a name="\textbf{em\_max}" with\\ utype="\textbf{Char.Spectral.Axis.Energy.Max}"\\ -datatype="float", ucd="em.energy" and unit="m" , containing the high energy bound for this particular sky position and -visibility time interval.} +datatype="float", ucd="em.energy" and unit="m" , containing the high energy bound for this particular sky position and observability time interval.} + +\item {Exactly one field \textbf{MAY }have a name="\textbf{max\_obs}" with\\ +utype="\textbf{Char.TimeAxis.Coverage.Support.Extent}"\\ with +datatype="float", ucd="time.duration" and unit="s" , containing the maximum observavility period for the given sky position at the given time.} \item {Exactly one field \textbf{MAY }have a name="\textbf{elevation\_min}" with\\ utype="\textbf{Char.Position.Axis.Min}"\\ with -datatype="float", ucd="angle.validity" and unit="deg" , containing the minimum elevation for this particular sky position and visibility -time interval.} +datatype="float", ucd="angle.validity" and unit="deg" , containing the minimum elevation for this particular sky position and observability time interval.} \item {Exactly one field \textbf{MAY }have a name="\textbf{elevation\_max}" with\\ utype="\textbf{Char.Position.Axis.Max}"\\ datatype="float", ucd="angle.validity" and unit="deg", containing the maximum elevation for this particular sky position and -visibility time interval.} +observability time interval.} \item {Exactly one field \textbf{MAY }have a name="\textbf{moon\_sep\_min}" datatype="float", ucd="angle.validity" and unit="deg" , containing the minimum Moon separation for this particular -sky position and visibility time interval.} +sky position and observability time interval.} \item {Exactly one field \textbf{MAY }have a name="\textbf{moon\_sep\_max}" datatype="float", ucd="angle.validity" and unit="deg" , containing the maximum Moon separation for this particular -sky position and visibility time interval.} +sky position and observability time interval.} \item {Exactly one field \textbf{MAY }have a name="\textbf{sun\_sep\_min}" with\\ datatype="float", ucd="angle.validity" and unit="deg" , containing the minimum Sun separation for this particular -sky position and visibility time interval.} +sky position and observability time interval.} \item {Exactly one field \textbf{MAY }have a name="\textbf{sun\_sep\_max}" with\\ datatype="float", ucd="angle.validity" and unit="deg" , containing the maximum Sun separation for this particular -sky position and visibility time interval.} +sky position and observability time interval.} \item {Exactly one field \textbf{MAY} have a name="\textbf{facility}" with datatype="char" and arraysize="*", ucd="meta.id;instr.tel",\\ @@ -649,10 +651,10 @@ \subsubsection{Standard output fields} Examples: HST/WFPC2, VLT/FORS2, SKA1/LOW11, etc} \end{itemize} -\subsubsection{ObjVisSAP \{query\} Service Descriptor} +\subsubsection{ObjObsSAP \{query\} Service Descriptor} The DataLink specification describes a mechanism for describing a service within a VOTable resource and recommends that services can -describe themselves with a special resource with name="this". ObjVisSAP +describe themselves with a special resource with name="this". ObjObsSAP \{query\} responses should include a descriptor describing both standard and custom query parameters (if applicable). The descriptor for a service with standard parameters (see 3.1) would be:\\ @@ -661,13 +663,13 @@ \subsubsection{ObjVisSAP \{query\} Service Descriptor} \begin{lstlisting}[language=XML] + value="ivo://ivoa.net/std/ObjObsSAP#query-0.3"/> + value="http://example.com/ObjObsSAP/query"/> - + \end{lstlisting} @@ -686,16 +688,16 @@ \section{Output Example} xsi:noNamespaceSchemaLocation=" xmlns:http://www.ivoa.net/xml/VOTable/VOTable-1.1.xsd" xmlns:ssldm="http://www.ivoa.net/xml/ -ObjectVisibilityDM/ObjectVisibilityDM-v1.0.xsd" +ObjectObservabilityDM/ObjectObservabilityDM-v1.0.xsd" version="1.0"> European Space Astronomy Centre. XMM-Newton SOC - -Object Visibility Simple Access Protocol (ObjVisSAP) +Object Observability Simple Access Protocol (ObjObsSAP) -ObjVisSAP +ObjObsSAP @@ -706,7 +708,7 @@ \section{Output Example} - @@ -734,7 +736,7 @@ \section{Output Example} \renewcommand{\thesection}{\Alph{section}.\arabic{section}} \setcounter{section}{0} \begin{appendices} -\section{ObjVisSAP data model summary} +\section{ObjObsSAP data model summary} \FloatBarrier \begin{table}[h] \tiny @@ -747,7 +749,7 @@ \section{ObjVisSAP data model summary} \textbf{t\_validity} & \textbf{Char.TimeAxis.Coverage.Time \newline (MUST)} & time.validity & Date when the \newline -visibility calculation will change (MJD) & +observability calculation will change (MJD) & float & d \\ \hline \textbf{validity\_accuracy} & \textbf{(MAY)} & & Level of confidence @@ -755,26 +757,26 @@ \section{ObjVisSAP data model summary} Accepted values= HIGH, MEDIUM, LOW & char, * & \\ \hline \textbf{validity\_predictor} & \textbf{(MAY)} & & Identifier (string -free representation) of the software used to calculate the visibility & +free representation) of the software used to calculate the observability & char, * & \\ \hline \textbf{t\_start} & \textbf{ Char.TimeAxis.Coverage.Bounds. \newline Limits.StartTime \newline (MUST)} & time.start & -Visibility window start time (MJD) & float & d \\ +observability window start time (MJD) & float & d \\ \hline \textbf{t\_stop} & \textbf{ Char.TimeAxis.Coverage.Bounds. \newline Limits.StopTime \newline (MUST)} & time.end & -Visibility widow end time (MJD) & float & d \\ +observability widow end time (MJD) & float & d \\ \hline -\textbf{t\_visibility} & \textbf{ +\textbf{t\_observability} & \textbf{ Char.TimeAxis.Coverage. \newline Support.Extent \newline (MUST)} & time.duration & -Visibility duration window & float & s \\ +observability duration window & float & s \\ \hline \textbf{pos\_angle} & \textbf{ Char.SpatialAxis.Coverage.Location. \newline @@ -785,7 +787,7 @@ \section{ObjVisSAP data model summary} \textbf{em\_threshold} & \textbf{ Char.Spectral.Axis.Energy.Threshold \newline (MAY)} & em.energy & Energy -threshold for this particular sky position and visibility time interval +threshold for this particular sky position and observability time interval & float & m \\ \hline \pagebreak @@ -796,41 +798,41 @@ \section{ObjVisSAP data model summary} \textbf{em\_min} & \textbf{Char.Spectral.Axis.Energy.Min \newline (MAY)} & em.energy & Energy minimum for this particular sky position and -visibility time interval & float & m \\ +observability time interval & float & m \\ \hline \textbf{em\_max} & \textbf{Char.Spectral.Axis.Energy.Max \newline (MAY)} & em.energy & Energy maximum for this particular sky position and -visibility time interval & float & m \\ +observability time interval & float & m \\ \hline \textbf{elevation\_min} & \textbf{ Char.SpatialAxis.Coverage. \newline Extent.angular\_distance \newline (MAY)} & phys.angDist -& Minimum elevation for this sky position and visibility time interval & +& Minimum elevation for this sky position and observability time interval & float & deg \\ \hline \textbf{elevation\_max} & \textbf{ Char.SpatialAxis.Coverage. \newline Extent.angular\_distance \newline (MAY)} & phys.angDist -& Maximum elevation for this sky position and visibility time interval & +& Maximum elevation for this sky position and observability time interval & float & deg \\ \hline \textbf{moon\_sep\_min} & \textbf{(MAY)} & phys.angDist & Minimum -Moon separation for this sky position and visibility time interval & +Moon separation for this sky position and observability time interval & float & deg \\ \hline \textbf{moon\_sep\_max} & \textbf{(MAY)} & phys.angDist & Maximum -Moon separation for this sky position and visibility time interval & +Moon separation for this sky position and observability time interval & float & deg \\ \hline \textbf{sun\_sep\_min} & \textbf{(MAY)} & phys.angDist & Minimum Sun -separation for this sky position and visibility time interval & float & +separation for this sky position and observability time interval & float & deg \\ \hline \textbf{sun\_sep\_max} & \textbf{(MAY)} & phys.angDist & Maximum Sun -separation for this sky position and visibility time interval & float & +separation for this sky position and observability time interval & float & deg \\ \hline \textbf{facility} & \textbf{Char.SpatialAxis.Coverage.Provenance.\newline ObsConfig.Facility.name} @@ -843,5 +845,25 @@ \section{ObjVisSAP data model summary} \end{adjustbox} \end{table} \FloatBarrier + +\section{Changes from Previous Versions} + +\begin{table}[h] + +\begin{tabularx}{\linewidth}{|L|c|l|} +\hline +\textbf{Change} & \textbf{Section} & \textbf{Version} \\ +\hline +Visibility concept has been replaced by observability & all & WD-20241027 \\ +\hline +min\_vis and max\_vis parameters have been replaced by +min\_obs and max\_obs, respectively & all & WD-20241027 \\ +\hline +t\_visibility column changed by t\_observability & all & WD-20241027 \\ +\hline +\end{tabularx} +\end{table} + + \end{appendices} \end{document} diff --git a/README.md b/README.md index b8c6a89..3debcda 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ -[![PDF-Preview](https://img.shields.io/badge/PDF-Preview-blue)](https://github.com/ivoa-std/ObjVisSAP/releases/download/auto-pdf-preview/ObjVisSAP-draft.pdf) +[![PDF-Preview](https://img.shields.io/badge/PDF-Preview-blue)](https://github.com/ivoa-std/ObjObsSAP/releases/download/auto-pdf-preview/ObjObsSAP-draft.pdf) -# ObjVisSAP - Object Visibility Simple Access Protocol +# ObjObsSAP - Object Observability Simple Access Protocol -The Object Visibility Simple Access Protocol (ObjVisSAP) is an IVOA Data +The Object Observability Simple Access Protocol (ObjObsSAP) is an IVOA Data Access protocol which defines the standard for retrieving object constraint-free visibility time intervals through a uniform interface within the VO framework for given object coordinates to be observed by a given -Astronomical Observatory. The ObjVisSAP services can be registered in an +Astronomical Observatory. The ObjObsSAP services can be registered in an IVOA Registry of Resources using the VOResource, Extension standard, having -a unique ResourceIdentifier in the registry. The ObjVisSAP interface is +a unique ResourceIdentifier in the registry. The ObjObsSAP interface is meant to be reasonably simple to be implemented by service providers. A basic query will be done introducing a set of sky coordinates and a given time period (optional). The service returns a list of constraint-free @@ -17,6 +17,12 @@ the service may support additional search parameters (some of which may be custom to that particular service) to more finely control the selection of the visibility periods. The specification also describes how the search on extra parameters has to be done. +# Name changed + +This protocol was previously named ObjVisSAP: Object Visibility Simple Access +Protocol. It has been renamed since the +[IVOA Interoperability Meeting in Nov. 2023 in Tucson](https://wiki.ivoa.net/twiki/bin/view/IVOA/InterOpNov2023) +(see [presentation](https://wiki.ivoa.net/internal/IVOA/InterOpNov2023DAL/ObjObsSAP_IVOA2023.pdf)). # Status @@ -26,9 +32,11 @@ Under development. Remember to checkout the repository with its submodules. - git clone --recurse-submodules https://github.com/ivoa-std/ObjVisSAP.git +```bash + git clone --recurse-submodules https://github.com/ivoa-std/ObjObsSAP.git +``` -Then: run "make" and hope you have all the necessary tools installed. +Then: run `make` and hope you have all the necessary tools installed. # License diff --git a/ivoatex b/ivoatex index cb58ec8..8f1c8d6 160000 --- a/ivoatex +++ b/ivoatex @@ -1 +1 @@ -Subproject commit cb58ec881b17a89dfc180d0bd2edcbba09638e0d +Subproject commit 8f1c8d6797c8514e705fd82b106fe8c5f2a55f63 diff --git a/ivoatexmeta.tex b/ivoatexmeta.tex index a720b83..5bb81ff 100644 --- a/ivoatexmeta.tex +++ b/ivoatexmeta.tex @@ -1,6 +1,6 @@ % GENERATED FILE -- edit this in the Makefile \newcommand{\ivoaDocversion}{1.0} -\newcommand{\ivoaDocdate}{2021-03-23} -\newcommand{\ivoaDocdatecode}{20210323} +\newcommand{\ivoaDocdate}{2024-11-18} +\newcommand{\ivoaDocdatecode}{20241118} \newcommand{\ivoaDoctype}{WD} -\newcommand{\ivoaDocname}{ObjVisSAP} +\newcommand{\ivoaDocname}{ObjObsSAP} diff --git a/role_diagram.pdf b/role_diagram.pdf index 81e4302..f4a9a12 100644 Binary files a/role_diagram.pdf and b/role_diagram.pdf differ diff --git a/role_diagram.svg b/role_diagram.svg index c4d77fe..874816f 100644 --- a/role_diagram.svg +++ b/role_diagram.svg @@ -48,7 +48,7 @@ DALI - ObjVisSAP + ObjObsSAP DataLink diff --git a/role_diagram.xml b/role_diagram.xml index fe2c6de..09baef2 100644 --- a/role_diagram.xml +++ b/role_diagram.xml @@ -13,7 +13,6 @@ with missing dependencies. - @@ -21,7 +20,7 @@ with missing dependencies. - +