NAV Navbar
Example XML Schema
  • Getting Started
  • User Management API
  • Floor Plan API
  • Receive Floor Plan API
  • Floor Plan XML
  • Symbols XML
  • Code Lists
  • Getting Started

    Using email

    1. Configure the export button

    Sign in to magicplan cloud as a workgroup admin and go to the export settings of your workgroup.

    Export settings

    Enter a public URL of your logo (1) and provide a description of your export button (2) which will be shown in magicplan.

    Enter the email address (3) to which published floor plans should be sent to.

    Save your configuration.

    2. Invite magicplan user to your workgroup (optional).

    In order for a user to test the export he needs to be in your workgroup. If necessary you can invite additional users to your workgroup.

    Sign in to magicplan cloud as a workgroup admin and go to your workgroup.

    You can invite additional members to your workgroup using the "Invite user" button (1).

    Invite1

    Enter the email address of the user you would like to invite and press "Invite".

    Invite2

    3. Create and publish a floor plan.

    Sign in to magicplan using an account that is part of the workgroup, create a floor plan and export it to your application using your applications export button.

    When the magicplan user publishes the floor plan, magicplan will send an email to the email address configured in the magicplan cloud.

    Using HTTP

    1. Setup HTTPS endpoints.

    This is the endpoints that will receive the floor plan from magicplan. You can choose the URL yourself. This guide uses the following example URL:

    https://example.com/update

    2. Get an evaluation API key.

    Send an email to partners@magic-plan.com, provide the URL from step 1 and request a customer ID and an API key for evaluation. Evaluation keys are valid for 30 days and can be renewed if necessary.

    This guide uses CUSTOMER_ID and API_SECRET_KEY as placeholders. You will need to replace placeholders with the values you received via email.

    3. Configure the export button

    Sign in to magicplan cloud as a workgroup admin and go to the export settings of your workgroup.

    Export settings2

    Enter a public URL of your logo (1) and provide a description of your export button (2) which will be shown in magicplan.

    Save your configuration.

    4. Create new magicplan account (optional).

    Create user request to magicplan:

    POST /newuser.php HTTP/1.1
    Host: cloud.sensopia.com
    Content-Type: application/x-www-form-urlencoded
    
    customer=CUSTOMER_ID&
    key=API_SECRET_KEY&
    email=EMAIL&
    password=PASSWORD&
    ref=USER_ID&
    onlyifexists=0
    

    Create user response from magicplan:

    <?xml version="1.0" encoding="UTF-8"?>
    <MagicPlanService>
      <status>0</status>
    </MagicPlanService>
    

    Before a user in magicplan can send floor plans to your application, their magicplan accounts need to be connected to your application.

    For testing purposes, it is recommended to create a new account. You can do this by sending the API request in the example. The EMAIL and PASSWORD parameters should be replaced by an actual email address and the desired password of the test user.

    For an actual application, USER_ID would be the ID of the user in your database. For testing, you can supply any string as the USER_ID.

    The new user will be in the same workgroup and therefore he will see the export button right away.

    5. Create and publish a floor plan.

    Sign in to magicplan using the test account, create a floor plan and export it to your application using your applications export button. You can then inspect the data that has been provided by magicplan.

    Receive request from magicplan:

    GET /update?key=API_SECRET_KEY&
    email=EMAIL&
    ref=USER_ID&
    planid=456dsf254a35&
    title=Plan+3&
    pdf=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2FCUSTOMER_ID%2FPlan3.pdf&
    jpg0=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2FCUSTOMER_ID%2FPlan3.jpg&
    dxf0=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2FCUSTOMER_ID%2FPlan3.dxf&
    png0=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2FCUSTOMER_ID%2FPlan3.png&
    png0_0=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2FCUSTOMER_ID%2FPlan3_r1.jpg&
    png0_1=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2FCUSTOMER_ID%2FPlan3_r2.jpg&
    svg0=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2FCUSTOMER_ID%2FPlan3.svg&
    xml=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2FCUSTOMER_ID%2FPlan3.xml&
    html=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35&
    embedded=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2Fembedded.html HTTP/1.1
    Host: example.com
    

    When the magicplan user publishes the floor plan, magicplan will send a GET request to the receive endpoint. The request will contain the URL of the floor plan files. The files should be downloaded within 24 hours after the GET request. An asynchronous download is recommended, i.e. after the receive request has been completed.

    User Management API

    Before a user in magicplan can send floor plans to your application, their magicplan accounts need to be connected to your application. To link an account in magicplan to your application you can use this request.

    For example, have the user enter his magicplan credentials in your application and use those information to call the API. Magicplan validates the user and will save the ref you provided which will help you to identify the user in your application.

    If your user does not have a magicplan account yet, a new magicplan account will be automatically created using the credentials provided. If you would prevent this behavior you can use the parameter onlyifexists to prevent a new magicplan account from being created.

    POST https://cloud.sensopia.com/newuser.php

    POST /newuser.php HTTP/1.1
    Host: cloud.sensopia.com
    Content-Type: application/x-www-form-urlencoded
    
    customer=3b2abe7cd80d&
    key=2aB193beHa42t1o09aqbJm3HFp1M3b8&
    email=john.doe%40example.com&
    password=mysecret&
    ref=1234567
    
    Parameter Required Description
    customer Yes Your customer ID provided by Sensopia.
    key Yes The magicplan API key provided by Sensopia.
    email Yes The user's email address. magicplan uses it as a login.
    password Yes The user's magicplan password. For an existing magicplan account, it must match the existing password. For a new magicplan account, it becomes the user's password. It must be at least 8 characters long.
    ref Yes A reference string that uniquely identifies this user in your database. magicplan will pass this parameter to your server in subsequent calls.
    onlyifexists No A flag indicating if the user must be connected only if it already exists or if it must be created even if it does not exist.
    1 = Connect user only if it already exists;
    0 = Always create user [default value].
    firstname No The user's first name.
    lastname No The user's last name.
    language No The 2-letter ISO code of the user’s language.
    department No The department/facility where the user is working.
    telephone No The telephone number.
    street No The name of the street.
    city No The name of the city.
    province No The name of the province or state.
    country No The 2-letter ISO country code.
    postalcode No The postal code or zip code.
    <?xml version="1.0" encoding="UTF-8"?>
    <MagicPlanService>
      <status>0</status>
    </MagicPlanService>
    
    <xs:element name="MagicPlanService">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="status">
            <xs:simpleType>
              <xs:restriction base="xs:integer">
                <xs:enumeration value="0"/>
                <xs:enumeration value="1"/>
                <xs:enumeration value="2"/>
                <xs:enumeration value="5"/>
                <xs:enumeration value="7"/>
                <xs:enumeration value="9"/>
                <xs:enumeration value="10"/>
                <xs:enumeration value="14"/>
                <xs:enumeration value="19"/>
              </xs:restriction>
            </xs:simpleType>
          </xs:element>
          <xs:element name="message" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    
    XML tag Value
    <status> 0 The request was a success.
    1 The API key is invalid.
    2 A parameter is missing or invalid.
    5 The given customer ID was not found.
    7 User not found with the given email address (when onlyifexists=1).
    9 The given password is not secure enough.
    10 An exception was thrown.
    14 The given password does not match the current password.
    19 A user is already registered with the given reference for this customer.
    <message> A human readable representation of the response

    Use this request to unlink any user account that has been previously linked to magicplan.

    POST https://cloud.sensopia.com/deleteuser.php

    POST /deleteuser.php HTTP/1.1
    Host: cloud.sensopia.com
    Content-Type: application/x-www-form-urlencoded
    
    customer=3b2abe7cd80d&
    key=2aB193beHa42t1o09aqbJm3HFp1M3b8&
    email=john.doe%40example.com&
    password=mysecret&
    ref=1234567
    
    Parameter Required Description
    customer Yes Your customer ID provided by Sensopia.
    key Yes The magicplan API key provided by Sensopia.
    email Yes The user's email address. Magicplan uses it as a login.
    password Yes The user's magicplan password.
    ref Yes A reference string that uniquely identifies this user in your database. If the user was configured with multiple references, only the given one is removed and the others remain active. Call this service once for each reference to remove them all.
    <?xml version="1.0" encoding="UTF-8"?>
    <MagicPlanService>
      <status>0</status>
    </MagicPlanService>
    
    <xs:element name="MagicPlanService">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="status">
            <xs:simpleType>
              <xs:restriction base="xs:integer">
                <xs:enumeration value="0"/>
                <xs:enumeration value="1"/>
                <xs:enumeration value="2"/>
                <xs:enumeration value="5"/>
                <xs:enumeration value="7"/>
                <xs:enumeration value="10"/>
                <xs:enumeration value="14"/>
                <xs:enumeration value="30"/>
              </xs:restriction>
            </xs:simpleType>
          </xs:element>
          <xs:element name="message" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    
    XML tag Value
    <status> 0 The request was a success.
    1 The API key is invalid.
    2 A parameter is missing or invalid.
    5 The given customer ID was not found.
    7 There is no user with the given email address.
    10 An exception was thrown.
    14 The given password does not match the current password.
    30 The user exists but is not associated with the given reference.
    <message> A human readable representation of the response

    Change password

    Use this request to change the password of a magicplan user.

    HTTP Request

    POST https://cloud.sensopia.com/changepassword.php

    Request

    POST /changepassword.php HTTP/1.1
    Host: cloud.sensopia.com
    Content-Type: application/x-www-form-urlencoded
    
    customer=3b2abe7cd80d&
    key=2aB193beHa42t1o09aqbJm3HFp1M3b8&
    email=john.doe%40example.com&
    password=mysecret&
    newpassword=moresecret
    
    Parameter Required Description
    customer Yes Your customer ID provided by Sensopia.
    key Yes The magicplan API key provided by Sensopia.
    email Yes The user's email address. Magicplan uses it as a login.
    password Yes The current password of the magicplan user.
    newpassword Yes The new password of the magicplan user. It must be at least 8 characters long.

    Response

    <?xml version="1.0" encoding="UTF-8"?>
    <MagicPlanService>
      <status>0</status>
    </MagicPlanService>
    
    <xs:element name="MagicPlanService">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="status">
            <xs:simpleType>
              <xs:restriction base="xs:integer">
                <xs:enumeration value="0"/>
                <xs:enumeration value="1"/>
                <xs:enumeration value="2"/>
                <xs:enumeration value="9"/>
                <xs:enumeration value="14"/>
              </xs:restriction>
            </xs:simpleType>
          </xs:element>
          <xs:element name="message" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    
    XML tag Value
    <status> 0 The request was a success.
    1 The API key is invalid.
    2 A parameter is missing or invalid.
    9 The given password does not match the current one or is invalid.
    14 There is no user with the given email address.
    <message> A human readable representation of the response

    Floor Plan API

    Create floor plan

    This request creates an empty floor plan with a list of attributes and dispatches it to a given user. Attributes can only be attached to the plan itself (as opposed to objects inside the plan) and the plan does not contain any rooms initially.

    For example, you can use this to prepare new plans with a given address and send them to your users in the field so that they can perform a survey.

    HTTP Request

    POST https://cloud.sensopia.com/dispatchplan.php

    Request

    POST /dispatchplan.php HTTP/1.1
    Host: cloud.sensopia.com
    Content-Type: application/x-www-form-urlencoded
    
    customer=3b2abe7cd80d&
    key=2aB193beHa42t1o09aqbJm3HFp1M3b8&
    email=john.doe%40example.com&
    type=1&
    name=Plan+1
    
    Parameter Required Description
    customer Yes Your customer ID provided by Sensopia.
    key Yes The magicplan API key provided by Sensopia.
    email Yes The user's email address. Magicplan uses it as a login.
    type Yes The type of plan to create (0=Residential, 1=Commercial)
    name Yes The name of the floor plan.
    streetnumber No The street number of the address.
    street No The name of the street.
    city No The name of the city.
    province No The name of the province or state.
    countryname No The name of the country.
    postalcode No The postal code or zip code.
    listing No For example a local project ID to assign to the floor plan. If specified, this ID is passed back to your application when exporting the floor plan. See also Link project.

    Response

    <?xml version="1.0" encoding="UTF-8"?>
    <MagicPlanService>
      <status>0</status>
      <planid>123467</planid>
    </MagicPlanService>
    
    <xs:element name="MagicPlanService">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="status">
            <xs:simpleType>
              <xs:restriction base="xs:integer">
                <xs:enumeration value="0"/>
                <xs:enumeration value="1"/>
                <xs:enumeration value="2"/>
                <xs:enumeration value="5"/>
                <xs:enumeration value="7"/>
                <xs:enumeration value="14"/>
              </xs:restriction>
            </xs:simpleType>
          </xs:element>
          <xs:element name="message" type="xs:string"/>
          <xs:element name="planid" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    
    XML tag Value
    <status> 0 The request was a success.
    1 The API key is invalid.
    2 A parameter is missing or invalid.
    5 There is no customer with the given customer ID.
    7 The email address is invalid or unspecified.
    14 There is no user with the given email address.
    <message> A human readable representation of the response
    <planid> The plan id of the created floor plan

    List floor plan files

    This request returns all files associated with a given floor plan or to all floor plans belonging to a given user.

    There are two options:

    1. To retrieve all files associated with a known floor plan, specify the floor plan unique identifier in the planid parameter and omit the email parameter. The planid can be obtained from magicplan when creating a new floor plan.

    2. To retrieve all files belonging to a known user, specify the user’s email address in the email parameter and omit the planid parameter.

    Sequence

    Pull

    HTTP Request

    POST https://cloud.sensopia.com/listfiles.php

    Request

    List all files for a floor plan

    POST /listfiles.php HTTP/1.1
    Host: cloud.sensopia.com
    Content-Type: application/x-www-form-urlencoded
    
    customer=3b2abe7cd80d&
    key=2aB193beHa42t1o09aqbJm3HFp1M3b8&
    planid=456dsf254a35
    

    List all files for a user

    POST /listfiles.php HTTP/1.1
    Host: cloud.sensopia.com
    Content-Type: application/x-www-form-urlencoded
    
    customer=3b2abe7cd80d&
    key=2aB193beHa42t1o09aqbJm3HFp1M3b8&
    email=john.doe%40example.com
    
    Parameter Required Description
    customer Yes Your customer ID provided by Sensopia.
    key Yes The magicplan API key provided by Sensopia.
    planid No The unique identifier of the floor plan the files are associated with. If specified, the most recent copy of the files based on the given floor plan are returned. The floor plan must belong to a member of the given customer’s workgroup.
    email No The user's email address. The user must be a member of the given customer’s workgroup.
    since No Unix timestamp, a date in seconds since 1970-01-01. All files returned will be more recent than the given date.

    Response

    <?xml version="1.0" encoding="UTF-8"?>
    <MagicPlanService>
      <file
        url='http://plans.sensopia.com/planid1/mycustomerid/Plan1.dxf'
        id='123467'
        name='Plan1.dxf'
        date='1523910982'
        type='dxf'
      />
      <file
        url='http://plans.sensopia.com/planid1/mycustomerid/Plan1.pdf'
        id='123467'
        name='Plan1.pdf'
        date='1523910982'
        type='pdf'
      />
      <file
        url='http://plans.sensopia.com/planid1/mycustomerid/Plan3.pdf'
        id='98765'
        name='Plan3.pdf'
        date='1523910984'
        type='pdf'
      />
      <service>listfiles</service>
      <status>0</status>
    </MagicPlanService>
    
    <xs:element name="MagicPlanService">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="file" type="file" minOccurs="0"/>
          <xs:element name="service" type="xs:string"/>
          <xs:element name="status">
            <xs:simpleType>
              <xs:restriction base="xs:integer">
                <xs:enumeration value="0"/>
                <xs:enumeration value="1"/>
                <xs:enumeration value="2"/>
                <xs:enumeration value="5"/>
                <xs:enumeration value="7"/>
                <xs:enumeration value="14"/>
              </xs:restriction>
            </xs:simpleType>
          </xs:element>
          <xs:element name="message" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    
    <xs:complexType name="file">
      <xs:attribute name="id" type="xs:string"/>
      <xs:attribute name="url" type="xs:string"/>
      <xs:attribute name="name" type="xs:string"/>
      <xs:attribute name="date" type="xs:unsignedInt"/>
      <xs:attribute name="type" type="xs:string"/>
    </xs:complexType>
    
    XML tag Value
    <status> 0 The request was a success.
    1 The API key is invalid.
    2 A parameter is missing or invalid.
    5 There is no customer with the given customer ID.
    7 The email address is invalid or unspecified.
    14 There is no user with the given email address.
    <service> The name of the service
    <message> A human readable representation of the response
    <file> see below

    Each <file>-element refers to file associated with floor plan.

    Attribute Description
    url The public URL from which the file can be downloaded.
    id The id of the plan to which the file belongs.
    name The filename of the file.
    date The date the file has been created.
    type The type of the file.

    User generated images

    <?xml version="1.0" encoding="UTF-8"?>
    <symbolInstance
      id="F-0-0"
      uid="5aec8337.df981fff"
      parentUid=""
      symbol="chair"
    >
      <values>
        <value key="image[0]">img0.png</value>
      </values>
    </symbolInstance>
    

    When processing the floor plan xml, you might want to download custom images that have been attached to objects in the floor plan. Images are stored at the base URL of the published floor plan.

    URL to the floor plan xml
    http://plans.sensopia.com/PLAN_ID/CUSTOMER_ID/plan.xml
    Base URL
    http://plans.sensopia.com/PLAN_ID

    To obtain the full path of the image you can combine the base URL of the floor plan with the relative path of the image. For example:

    http://plans.sensopia.com/PLAN_ID/img0.png

    Receive Floor Plan API

    Exporting floor plans from magicplan works out of the box.

    However, you may choose to implement an additional step in which your users are able to select a specific project from your application for floor plans that are not already linked to a project prior to exporting that floor plan.

    If configured, magicplan uses this service to obtain a list of projects from your application and present them to your users at publishing time. Magicplan then passes the project selected by the user in subsequent calls.

    If this service is not configured, floor plans that do not already have a project assigned are submitted to your server without an assigned project.

    Add a <warnOnReplace> element that contains value 1 if you want magicplan to warn the user that the operation will overwrite an existing project.

    GET https://yourserverurl/getlistings

    GET /getlistings?key=3b2abe7cd80d&
    email=john.doe%40example.com&
    latitude=40.7143528&
    longitude=-74.0059731&
    street=1617++Toy+Avenue&
    city=Ajax+Pickering&
    province=Ontario&
    country=Canada&
    postalcode=L1W+3N9 HTTP/1.1
    Host: yourserverurl
    
    Parameter Required Description
    key Yes The magicplan API key provided by Sensopia
    email Yes The user's email address.
    ref No The unique reference string that you supplied when creating the user. Absent if no reference was supplied.
    latitude Yes The latitude of the property.
    longitude Yes The longitude of the property.
    street Yes The street number and name of the property.
    city Yes The city of the property.
    province Yes The province of the property.
    country Yes The country of the property.
    postalcode Yes The postal/zip code of the property.
    <?xml version="1.0" encoding="UTF-8"?>
    <MagicPlanService>
      <status>0</status>
      <listing>
        <id>0001</id>
        <title>148, rue de Normandie</title>
      </listing>
      <listing>
        <id>00034</id>
        <title>520, boul. de Picardie</title>
      </listing>
    </MagicPlanService>
    

    Warns the user that he would overwrite a project

    <?xml version="1.0" encoding="UTF-8"?>
    <MagicPlanService>
      <status>0</status>
      <listing>
        <id>00034</id>
        <title>520, boul. de Picardie</title>
        <warnOnReplace>1</warnOnReplace>
      </listing>
    </MagicPlanService>
    
    <xs:element name="MagicPlanService">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="status">
            <xs:simpleType>
              <xs:restriction base="xs:integer">
                <xs:enumeration value="0"/>
                <xs:enumeration value="1"/>
                <xs:enumeration value="2"/>
                <xs:enumeration value="14"/>
              </xs:restriction>
            </xs:simpleType>
          </xs:element>
          <xs:element name="listing" type="listing" minOccurs="0"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    
    <xs:complexType name="listing">
      <xs:sequence>
        <xs:element name="id" type="xs:string"/>
        <xs:element name="title" type="xs:string"/>
        <xs:element name="warnOnReplace" minOccurs="0">
          <xs:simpleType>
            <xs:enumeration value="0"/>
            <xs:enumeration value="1"/>
          </xs:simpleType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
    
    XML tag Value
    <status> 0 The request was a success.
    1 The API key is invalid.
    2 A parameter is missing or invalid.
    14 The given user reference or email does not exist.
    <listing> see below

    Each <listing>-element encapsulates a project.

    Attribute Description
    id The unique identifier of a project.
    title The title of a project. Magicplan will present this string to the user.
    warnOnReplace Warns the user that the operation will overwrite an existing project.
    <?xml version="1.0" encoding="UTF-8"?>
    <MagicPlanService>
      <status>0</status>
      <listing>
        <id>0001</id>
        <title>148, rue de Normandie</title>
      </listing>
      <listing>
        <id>__NEW__</id>
        <title>New Project</title>
      </listing>
    </MagicPlanService>
    

    The newly created projects is included in subsequent responses

    <?xml version="1.0" encoding="UTF-8"?>
    <MagicPlanService>
      <status>0</status>
      <listing>
        <id>0001</id>
        <title>148, rue de Normandie</title>
      </listing>
      <listing>
        <id>0002</id>
        <title>520, boul. de Picardie</title>
      </listing>
      <listing>
        <id>__NEW__</id>
        <title>New Project</title>
      </listing>
    </MagicPlanService>
    

    If no suitable project exists yet, you can use this service to let the user create a new project in your application.

    You can add a placeholder labelled something like New Project at the end or the beginning of the list with an ID that you can easily recognize as not being already in your database. This would allow the user to create a new project on the fly as he published his floor plan. On a subsequent export the newly created project will show up in the list.

    Authorize transfer

    This service applies to partners who are not using a subscription model.

    Implementing this service allows you to confirm whether your users are allowed to publish a floor plan to your application. Per default magicplan will authorize all floor plans.

    If this service is configured, magicplan calls it when a user requests the right to publish a floor plan. Once your application receives this request, you may accept or decline the transfer, based on your own account and payment information.

    If the user has previously selected a project or the floor plan has been dispatched, the project ID will be passed with the request in order to assist you in determining whether or not to accept the payment.

    HTTP Request

    GET https://yourserverurl/cansend

    Request

    GET /cansend?key=3b2abe7cd80d&
    email=john.doe%40example.com&
    ref=1234567&
    planid=456dsf254a35 HTTP/1.1
    Host: yourserverurl
    
    Parameter Required Description
    key Yes The magicplan API key provided by Sensopia
    email Yes The user's email address.
    ref Yes The unique reference string that you passed when creating the user. If you supplied multiple refs, this is the one the user picked before sending you his floor plan.
    listing No The ID of the project the plan has been assigned to.
    planid Yes The unique identifier of the plan being updated.

    Response

    <?xml version="1.0" encoding="UTF-8"?>
    <MagicPlanService>
      <status>0</status>
      <confirmation>ABCD1234</confirmation>
    </MagicPlanService>
    
    <xs:element name="MagicPlanService">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="status">
            <xs:simpleType>
              <xs:restriction base="xs:integer">
                <xs:enumeration value="0"/>
                <xs:enumeration value="1"/>
                <xs:enumeration value="2"/>
                <xs:enumeration value="14"/>
                <xs:enumeration value="18"/>
              </xs:restriction>
            </xs:simpleType>
          </xs:element>
          <xs:element name="confirmation" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    
    XML tag Value
    <status> 0 The request was a success.
    1 The API key is invalid.
    2 A parameter is missing or invalid.
    14 The given user reference or email does not exist.
    18 The given listing does not exist.
    <confirmation> A string that is logged by magicplan to allow future payment reconciliation.

    Floor Plan Updated

    Magicplan calls this webhook to notify your application that a user has generated new files or updated existing files. Implementing this webhook is mandatory for the "Send to [YourApplication]" button to work.

    Once your application receives this request, it should queue the URLs and download the files as soon as possible. Files are guaranteed to be available for 24 hours.

    If the request fails, the user in magicplan will see an error and is able to retry publishing the plan.

    Depending on your configuration the request includes several file types representing the exported floor plan. For worldwide interoperability each string or file url is encoded in a two-step process:

    1. The character string is converted into a sequence of bytes using UTF-8 encoding.
    2. Each byte that is not an ASCII letter or digit is converted to %HH, where HH is the hexadecimal value of the byte (e.g. électrique becomes %C3%A9lectrique).

    Sequence

    Push

    HTTP Request

    GET https://yourserverurl/update

    Request

    GET /update?key=3b2abe7cd80d&
    email=john.doe%40example.com&
    ref=1234567&
    planid=456dsf254a35&
    title=Plan+3&
    pdf=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2Fmycustomerid%2FPlan3.pdf&
    jpg0=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2Fmycustomerid%2FPlan3.jpg&
    dxf0=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2Fmycustomerid%2FPlan3.dxf&
    png0=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2Fmycustomerid%2FPlan3.png&
    png0_0=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2Fmycustomerid%2FPlan3_r1.jpg&
    png0_1=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2Fmycustomerid%2FPlan3_r2.jpg&
    svg0=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2Fmycustomerid%2FPlan3.svg&
    xml=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2Fmycustomerid%2FPlan3.xml&
    html=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35&
    embedded=http%3A%2F%2Fplans.sensopia.com%2F456dsf254a35%2Fembedded.html HTTP/1.1
    Host: yourserverurl
    
    Parameter Required Description
    key Yes The magicplan API key provided by Sensopia
    email Yes The user's email address.
    ref Yes The unique reference string that you passed when creating the user. If you supplied multiple refs, this is the one the user picked before sending you his floor plan.
    title Yes A human-readable title of the plans being updated.
    planid Yes The unique identifier of the plan being updated.
    listing No The ID of the project the plan has been assigned to.
    pdf No The URL of the updated PDF file.
    jpg0, jpg1, ... jpgF No The URL of a JPG file. There is one JPG file per floor up to F (floor count - 1).
    dxf0, dxf1, ... dxfF No The URL of a DXF file. There is one DXF file per floor up to F (floor count - 1).
    png0, png1, ... pngF No The URL of a PNG file. There is one PNG file per floor up to F (floor count - 1) representing the whole floor following the naming convention png0, png1, ... pngF.
    png0_0, png0_1, ... png0_R No Additionally, there is one PNG file per room on each floor following the naming convention pngf_0, pngf_1, ... pngf_R where f is the index of the floor in the XML file, 0 and 1 are the indices of the rooms in the XML file up to R (room count – 1 on floor f).
    svg0, svg1, ... svgn No The URL of an SVG file. There is one SVG file per floor.
    xml No The URL of the updated magicplan file.
    html No The URL of the updated Web site file. In this case, simply store the URL (do not download the web site).

    User generated images

    <?xml version="1.0" encoding="UTF-8"?>
    <symbolInstance
      id="F-0-0"
      uid="5aec8337.df981fff"
      parentUid=""
      symbol="chair"
    >
      <values>
        <value key="image[0]">img0.png</value>
      </values>
    </symbolInstance>
    

    When processing the floor plan xml, you might want to download custom images that have been attached to objects in the floor plan. Images are stored at the base URL of the published floor plan.

    URL to the floor plan xml
    http://plans.sensopia.com/PLAN_ID/CUSTOMER_ID/plan.xml
    Base URL
    http://plans.sensopia.com/PLAN_ID

    To obtain the full path of the image you can combine the base URL of the floor plan with the relative path of the image. For example:

    http://plans.sensopia.com/PLAN_ID/img0.png

    If configured, the first time a magicplan user that is not yet linked to your application attempts to send files to your application, magicplan sends a GET request.

    Your application returns a ref which will be saved by magicplan, see also Link account. If the given email address matches multiple users in your database, simply return all possible user IDs. Magicplan will let the user pick which account he wants to send his files to. The refs have to be human readable (such as login names) as they will be presented to the magicplan user in a list.

    GET https://yourserverurl/connect

    GET /connect?key=3b2abe7cd80d&
    email=john.doe%40example.com&
    password=secret HTTP/1.1
    Host: yourserverurl
    
    Parameter Required Description
    key Yes The magicplan API key provided by Sensopia.
    email Yes The user's email address. Magicplan uses it as a login.
    password Yes The user's password. For an existing account, it must match the existing password. For a new account, it becomes the user's password. The password can be a temporary string that the user should change.
    onlyifexists No A flag indicating if the user must be connected only if it already exists or if it must be created even if it does not exist.
    1 = Connect user only if it already exists;
    0 = Always create user [default value].
    firstname No The user's first name.
    lastname No The user's last name.

    One account matches

    <?xml version="1.0" encoding="UTF-8"?>
    <MagicPlanService>
      <status>0</status>
      <ref>ABCDEF1234</ref>
    </MagicPlanService>
    

    Multiple accounts match

    <?xml version="1.0" encoding="UTF-8"?>
    <MagicPlanService>
      <status>0</status>
      <ref>ABCDEF1234</ref>
      <ref>DHCDGH4375</ref>
      <ref>FJCDRT9045</ref>
    </MagicPlanService>
    
    <xs:element name="MagicPlanService">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="status">
            <xs:simpleType>
              <xs:restriction base="xs:integer">
                <xs:enumeration value="0"/>
                <xs:enumeration value="1"/>
                <xs:enumeration value="2"/>
                <xs:enumeration value="3"/>
                <xs:enumeration value="14"/>
              </xs:restriction>
            </xs:simpleType>
          </xs:element>
          <xs:element name="ref" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    
    XML tag Value
    <status> 0 The request was a success.
    1 The API key is invalid.
    2 A parameter is missing or invalid.
    3 A user is already registered with the given email address.
    14 User not found (when onlyifexists=1).
    <message> A human readable representation of the response
    <ref> A reference string that uniquely identifies this user in your database. Magicplan will pass this parameter to your server in subsequent calls. If the given email address matches multiple users in your database, simply return all possible user IDs.

    Floor Plan XML

    The following section describes the XML format of a magicplan file. Each file contains all the floor plans of a single property.

    At the root of the XML file is a <plan>-element. This element contains attributes of the property as well as a list of <floor>-elements representing the plans of various floors.

    Plan

    <?xml version="1.0" encoding="UTF-8"?>
    <plan
      id="20eb114d31f0b"
    
      name="Plan 1"
      type="0"
    
      interiorWallWidth="0.12000"
      exteriorWallWidth="0.25000"
    
      streetNumber="1"
      street="Any Street"
      city="Any Town"
      province="Any State"
      postalCode="12345"
      country="Canada"
    
      latitude="40.7143528"
      longitude="-74.0059731"
      altitude="10.00"
    >
      <floor></floor>
    </plan>
    
    <xs:element name="plan">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="values" minOccurs="0"/>
          <xs:element name="floor" maxOccurs="unbounded"/>
        </xs:sequence>
    
        <xs:attribute name="id" type="xs:string" use="required"/>
    
        <xs:attribute name="type" use="required">
          <xs:simpleType>
            <xs:restriction base="xs:integer">
              <xs:enumeration value="0"/>
              <xs:enumeration value="1"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
        <xs:attribute name="name" type="xs:string" use="required"/>
    
        <xs:attribute name="interiorWallWidth" type="xs:decimal" use="required"/>
        <xs:attribute name="exteriorWallWidth" type="xs:decimal" use="required"/>
    
        <xs:attribute name="streetNumber" type="xs:string"/>
        <xs:attribute name="street" type="xs:string"/>
        <xs:attribute name="city" type="xs:string"/>
        <xs:attribute name="province" type="xs:string"/>
        <xs:attribute name="postalCode" type="xs:string"/>
        <xs:attribute name="country" type="xs:string" use="required"/>
    
        <xs:attribute name="latitude" type="xs:decimal"/>
        <xs:attribute name="longitude" type="xs:decimal"/>
        <xs:attribute name="altitude" type="xs:decimal"/>
      </xs:complexType>
    </xs:element>
    

    A <plan>-element represents a project you see in magicplan. It is the root element of the XML.

    Screenshot

    Attribute Description
    id A unique identifier of the plan as assigned by Sensopia.
    name The human-readable name of the plan. This is the same text as the title parameter mentioned in the Web Services documentation.
    type The type of plan:
    0 for residential,
    1 for commercial
    interiorWallWidth The width of interior walls in meters as specified by the user. The actual wall width in the file may vary slightly from wall to wall due to incompatible measurements entered by the user. [Default 0.12]
    exteriorWallWidth The width of exterior walls. [Default 0.25]
    country The country the building is located in (ISO 3166).
    Optional attributes to locate the project

    Screenshot

    Attribute Description
    streetNumber The civic number of the building.
    street The name of the street the building is on.
    city The city the building is located in.
    province The state or province the building is located in.
    postalCode The postal or zip code assigned to the building.
    latitude The latitude of the building in meters as a floating point number.
    longitude The longitude of the building in meters as a floating point number.
    altitude The altitude of the building in meters as a floating point number.

    Floor

    <?xml version="1.0" encoding="UTF-8"?>
    <floor
      floorType="0"
      areaWithoutWalls="12.50"
      areaWithWalls="17.97"
      areaWithInteriorWallsOnly="12.50"
    >
      <symbolInstance></symbolInstance>
      <floorRoom></floorRoom>
      <exploded></exploded>
      <wires></wires>
    </floor>
    
    <xs:element name="floor">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="symbolInstance" minOccurs="0" maxOccurs="unbounded"/>
          <xs:element name="floorRoom" maxOccurs="unbounded"/>
          <xs:element name="exploded"/>
          <xs:element name="wires" minOccurs="0"/>
        </xs:sequence>
        <xs:attribute name="floorType" type="xs:string" use="required"/>
        <xs:attribute name="areaWithoutWalls" type="xs:decimal"/>
        <xs:attribute name="areaWithWalls" type="xs:decimal"/>
        <xs:attribute name="areaWithInteriorWallsOnly" type="xs:decimal"/>
      </xs:complexType>
    </xs:element>
    

    Each <plan>-element contains a list of <floor>-elements representing the plan for each floor.

    Screenshot

    Attribute Description
    floorType A number representing the type of floor. See list of available types in the Code List.
    areaWithoutWalls Pre-computed number representing the area without walls.
    areaWithWalls Pre-computed number representing the area with walls.
    areaWithInteriorWallsOnly Pre-computed number representing the area with only interior walls.

    Screenshot

    Exploded Floor vs. Room

    <?xml version="1.0" encoding="UTF-8"?>
    <floor>
      <floorRoom></floorRoom>
      <floorRoom></floorRoom>
      <exploded></exploded>
    </floor>
    

    Each <floor>-element contains two equivalent descriptions of the same floor plan:

    1. The <exploded>-element represents the whole floor with absolute coordinates. Walls and doors are only described once in this representation and are not grouped per room. This representation is better suited for building the floor in 3D or CAD and other drawing software that only need a line drawing without the room nomenclature.

    2. A list of <floorRoom>-elements describe each room individually. Connecting walls and doors are described twice in this format. This representation is semantically rich and allows determining in which room lies any [x, y] coordinate on the floor plan.

    Exploded Floor

    <?xml version="1.0" encoding="UTF-8"?>
    <exploded>
      <wall></wall>
      <door></door>
      <window></window>
      <furniture></furniture>
    </exploded>
    
    <xs:element name="exploded">
      <xs:complexType>
        <xs:sequence>
          <xs:choice maxOccurs="unbounded">
            <xs:element name="wall"/>
            <xs:element name="door"/>
            <xs:element name="window"/>
            <xs:element name="furniture"/>
          </xs:choice>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    

    The <exploded>-element represents the whole floor with absolute coordinates. Walls and doors are only described once in this representation and are not grouped per room.

    See also Rooms if you prefer a description per room.

    Screenshot

    Wall

    The <wall>-element represents a wall on the current floor.

    Point

    <?xml version="1.0" encoding="UTF-8"?>
    <wall>
      <point x="-5.912" y="-6.035"/>
      <point x="-5.912" y="-2.927"/>
    </wall>
    
    <xs:element name="wall">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="point" minOccurs="2" maxOccurs="2">
            <xs:complexType>
              <xs:attribute name="x" type="xs:decimal" use="required"/>
              <xs:attribute name="y" type="xs:decimal" use="required"/>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    

    Screenshot

    The coordinates of one vertex (corner) of a broken line representing a wall in its exploded representation. Points are positioned on an imaginary line located at the center of the wall.

    Attribute Description
    x The corrected horizontal position of the corner relatively to the center of the floor plan, in meters, as a floating point number. This value should be used when drawing an assembled floor plan.
    y The corrected vertical position of the corner relatively to the center of the floor plan, in meters, as a floating point number. This value should be used when drawing an assembled floor plan.

    Interior vs. exterior wall

    If there is a room attached to the other side of the wall, the part that is connected is an interior wall (1).

    If there is no adjacent room the wall is an exterior wall (2).

    Screenshot

    Wall thickness

    The thickness of the wall can be obtained from the <plan>-element (see Plan) and its respective attributes interiorWallWidth and exteriorWallWidth.

    On some occasion those values are overwritten. In this case please look at the parent <floor>-element's symbol instance and its properties. For more information, see SymbolInstance, Floor.

    Door

    <?xml version="1.0" encoding="UTF-8"?>
    <door
      symbolInstance="W-1-1"
    
      x1="-8.654"
      y1="-0.951"
    
      x2="-7.713"
      y2="-0.951"
    
      width="0.941"
      orientation="3"
    />
    
    <xs:element name="door">
      <xs:complexType>
        <xs:attribute name="symbolInstance" type="xs:string" use="required"/>
        <xs:attribute name="x1" type="xs:decimal" use="required"/>
        <xs:attribute name="y1" type="xs:decimal" use="required"/>
        <xs:attribute name="x2" type="xs:decimal" use="required"/>
        <xs:attribute name="y2" type="xs:decimal" use="required"/>
        <xs:attribute name="width" type="xs:decimal" use="required"/>
        <xs:attribute name="orientation" type="orientation" use="required"/>
      </xs:complexType>
    </xs:element>
    
    <xs:simpleType name="orientation">
      <xs:restriction base="xs:integer">
        <xs:minInclusive value="0"/>
        <xs:maxInclusive value="3"/>
      </xs:restriction>
    </xs:simpleType>
    

    The <door>-element represents a door on the current floor. Each door is only represented once.

    Screenshot

    Attribute Description
    symbolInstance The unique identifier of the <symbolInstance> element containing data attached to this door. The symbol instance contains the symbol ID.
    x1 The horizontal position of the first extremity of the door relatively to the center of the floor plan, in meters, as a floating point number.
    y1 The vertical position of the first extremity of the door relatively to the center of the floor plan, in meters, as a floating point number.
    x2 The horizontal position of the second extremity of the door relatively to the center of the floor plan, in meters, as a floating point number.
    y2 The vertical position of the second extremity of the door relatively to the center of the floor plan, in meters, as a floating point number.
    width The width of the door in meters represented by a floating point number. This value should be used when drawing an assembled floor plan.
    orientation The orientation of the door. Inconsistent door orientations are unified across rooms and may differ from the original orientation. This value should be used when drawing an assembled floor plan. The orientation is a number between 0 and 3 obtained by combining two bit values: bit 0, set if door opens towards the outside; bit 1, set if the door opens to the right.

    Window

    <?xml version="1.0" encoding="UTF-8"?>
    <window
      symbolInstance="W-0-1"
    
      x1="-8.435"
      y1="-6.036"
    
      x2="-6.447"
      y2="-6.036"
    
      width="1.988"
      orientation="0"
    />
    
    <xs:element name="window">
      <xs:complexType>
        <xs:attribute name="symbolInstance" type="xs:string" use="required"/>
        <xs:attribute name="x1" type="xs:decimal" use="required"/>
        <xs:attribute name="y1" type="xs:decimal" use="required"/>
        <xs:attribute name="x2" type="xs:decimal" use="required"/>
        <xs:attribute name="y2" type="xs:decimal" use="required"/>
        <xs:attribute name="width" type="xs:decimal" use="required"/>
        <xs:attribute name="orientation" type="orientation" use="required"/>
      </xs:complexType>
    </xs:element>
    
    <xs:simpleType name="orientation">
      <xs:restriction base="xs:integer">
        <xs:minInclusive value="0"/>
        <xs:maxInclusive value="3"/>
      </xs:restriction>
    </xs:simpleType>
    

    The <window>-element represents a window on the current floor. Each window is only represented once.

    Screenshot

    Attribute Description
    symbolInstance The unique identifier of the <symbolInstance> element containing data attached to this window. The symbol instance contains the symbol ID.
    x1 The horizontal position of the first extremity of the window relatively to the center of the floor plan, in meters, as a floating point number.
    y1 The vertical position of the first extremity of the window relatively to the center of the floor plan, in meters, as a floating point number.
    x2 The horizontal position of the second extremity of the window relatively to the center of the floor plan, in meters, as a floating point number.
    y2 The vertical position of the second extremity of the window relatively to the center of the floor plan, in meters, as a floating point number.
    width The width of the window in meters represented by a floating point number. This value should be used when drawing an assembled floor plan.
    orientation The orientation of the window. The orientation is a number between 0 and 3 specifying which way the window is facing and if it opens to the left or the right. This value should be used when drawing an assembled floor plan.

    Furniture

    <?xml version="1.0" encoding="UTF-8"?>
    <furniture
      symbolInstance="F-0-0"
    
      x="-6.989"
      y="-4.551"
    
      width="1.600"
      depth="2.037"
      angle="1.570"
    />
    
    <xs:element name="furniture">
      <xs:complexType>
        <xs:attribute name="symbolInstance" type="xs:string" use="required"/>
        <xs:attribute name="x" type="xs:decimal" use="required"/>
        <xs:attribute name="y" type="xs:decimal" use="required"/>
        <xs:attribute name="width" type="xs:decimal" use="required"/>
        <xs:attribute name="depth" type="xs:decimal" use="required"/>
        <xs:attribute name="angle" type="xs:decimal" use="required"/>
      </xs:complexType>
    </xs:element>
    

    The <furniture>-element represents a piece of furniture on the current floor.

    Screenshot

    Attribute Description
    symbolInstance The unique identifier of the <symbolInstance> element containing data attached to this piece of furniture. The symbol instance contains the symbol ID.
    x The horizontal position of the piece of furniture relatively to the center of the floor plan, in meters, as a floating point number.
    y The vertical position of the piece of furniture relatively to the center of the floor plan, in meters, as a floating point number.
    width The width of the piece of furniture in meters, as a floating point number.
    depth The depth of the piece of furniture in meters, as a floating point number.
    angle The angle of the piece of furniture in radians, as a floating point number.

    Room

    Each <floor>-element can contain multiple rooms (<floorRoom>).

    Screenshot

    The <floorRoom>-element describes each room individually.

    See also Exploded Floor if you prefer a description of all the rooms on the whole floor.

    <?xml version="1.0" encoding="UTF-8"?>
    <floorRoom
      uid="1441896884.002797"
      type="Kitchen"
    
      x="-7.72971"
      y="-3.49303"
      rotation="0.0"
    
      perimeter="16.96300"
      area="13.74133"
    >
      <point></point>
      <door />
      <window />
      <furniture />
      <values></values>
    </floor>
    
    <xs:element name="floorRoom">
      <xs:complexType>
        <xs:sequence>
          <xs:choice maxOccurs="unbounded">
            <xs:sequence>
              <xs:element name="point" maxOccurs="unbounded"/>
            </xs:sequence>
            <xs:sequence>
              <xs:element name="door"/>
            </xs:sequence>
            <xs:sequence>
              <xs:element name="window"/>
            </xs:sequence>
            <xs:sequence>
              <xs:element name="furniture"/>
            </xs:sequence>
            <xs:element name="values" minOccurs="0"/>
          </xs:choice>
        </xs:sequence>
        <xs:attribute name="uid" type="xs:string" use="required"/>
        <xs:attribute name="type" type="xs:string" use="required"/>
        <xs:attribute name="x" type="xs:decimal" use="required"/>
        <xs:attribute name="y" type="xs:decimal" use="required"/>
        <xs:attribute name="rotation" type="xs:decimal" use="required"/>
        <xs:attribute name="perimeter" type="xs:decimal"/>
        <xs:attribute name="area" type="xs:decimal"/>
      </xs:complexType>
    </xs:element>
    

    Screenshot

    Attribute Description
    uid Unique id of a room as assigned by Sensopia in order to track a room.
    type The type of room. The text description may be part of the predefined list of rooms in English or an ad hoc description entered by the user in any language.
    x The horizontal position of the center of the room on the floor plan in meters as a floating point number.
    y The vertical position of the center of the room on the floor plan in meters as a floating point number.
    rotation The angle of the floor in radians.

    Optional attributes

    Attribute Description
    perimeter The perimeter of the floor in meters.
    area The area of the floor in square meters.

    Point

    <?xml version="1.0" encoding="UTF-8"?>
    <point
      snappedX="0.97750"
      snappedY="-1.25850"
    />
    
    <xs:element name="point">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="values" minOccurs="0"/>
        </xs:sequence>
        <xs:attribute name="snappedX" type="xs:decimal" use="required"/>
        <xs:attribute name="snappedY" type="xs:decimal" use="required"/>
      </xs:complexType>
    </xs:element>
    

    The <point>-element represents corner in the current room (the intersection of two walls). Points are positioned on an imaginary line located at the center of the wall.

    The list of points are ordered clockwise.

    Screenshot

    Attribute Description
    snappedX The corrected horizontal position of the corner relatively to the center of the room, in meters, as a floating point number. This value should be used when drawing an assembled floor plan.
    snappedY The corrected vertical position of the corner relatively to the center of the room, in meters, as a floating point number. This value should be used when drawing an assembled floor plan.

    Door

    <?xml version="1.0" encoding="UTF-8"?>
    <door
      symbolInstance="W-2-1"
    
      point="3"
    
      snappedPosition="0.68850"
    
      snappedWidth="0.75000"
      snappedOrientation="0"
      insetZ="0.0"
    />
    
    <xs:element name="door">
      <xs:complexType>
        <xs:attribute name="symbolInstance" type="xs:string" use="required"/>
        <xs:attribute name="point" use="required">
          <xs:simpleType>
            <xs:restriction base="xs:integer">
              <xs:minInclusive value="0"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
        <xs:attribute name="snappedPosition" type="position" use="required"/>
        <xs:attribute name="snappedWidth" type="xs:decimal" use="required"/>
        <xs:attribute name="snappedOrientation" type="orientation" use="required"/>
        <xs:attribute name="insetZ" type="xs:decimal" use="required"/>
      </xs:complexType>
    </xs:element>
    
    <xs:simpleType name="orientation">
      <xs:restriction base="xs:integer">
        <xs:minInclusive value="0"/>
        <xs:maxInclusive value="3"/>
      </xs:restriction>
    </xs:simpleType>
    
    <xs:simpleType name="position">
      <xs:restriction base="xs:decimal">
        <xs:minInclusive value="0.0"/>
        <xs:maxInclusive value="1.0"/>
      </xs:restriction>
    </xs:simpleType>
    

    The <door>-element represents a door located on a wall in the current room. If the door is connecting two rooms, it is represented once on each wall of each room. See also SymbolInstance for more information.

    Screenshot

    Attribute Description
    symbolInstance The unique identifier of the <symbolInstance> element containing data attached to this door. The symbol instance contains the symbol ID.
    point The index 0-based of the <point> element starting the wall containing the door.
    snappedPosition The corrected relative position of the center of the door on the wall represented by a floating point number between 0.0 and 1.0. This value should be used when drawing an assembled floor plan.
    snappedWidth The corrected width of the door in meters represented by a floating point number. This value should be used when drawing an assembled floor plan.
    snappedOrientation The corrected orientation of the door after the rooms are assembled. Inconsistent door orientations are unified across rooms and may differ from the original orientation. This value should be used when drawing an assembled floor plan. The orientation is a number between 0 and 3 obtained by combining two bit values: bit 0, set if door opens towards the outside; bit 1, set if the door opens to the right.
    insetZ Floating point number in meters to determine how far the object is into the wall. Positive values show that the object goes away from the wall and into the room. Negative values show that the object goes inside the wall. For example, if you would like to center the object directly onto the wall, you can use -(interior wall thickness/2).

    Window

    <?xml version="1.0" encoding="UTF-8"?>
    <window
      symbolInstance="W-0-0"
    
      point="6"
    
      snappedPosition="0.67558"
    
      snappedWidth="1.28213"
      snappedOrientation="0"
      insetZ="-0.06"
    />
    
    <xs:element name="window">
      <xs:complexType>
        <xs:attribute name="symbolInstance" type="xs:string" use="required"/>
        <xs:attribute name="point" use="required">
          <xs:simpleType>
            <xs:restriction base="xs:integer">
              <xs:minInclusive value="0"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
        <xs:attribute name="snappedPosition" type="position" use="required"/>
        <xs:attribute name="snappedWidth" type="xs:decimal" use="required"/>
        <xs:attribute name="snappedOrientation" type="orientation" use="required"/>
        <xs:attribute name="insetZ" type="xs:decimal" use="required"/>
      </xs:complexType>
    </xs:element>
    
    <xs:simpleType name="orientation">
      <xs:restriction base="xs:integer">
        <xs:minInclusive value="0"/>
        <xs:maxInclusive value="3"/>
      </xs:restriction>
    </xs:simpleType>
    
    <xs:simpleType name="position">
      <xs:restriction base="xs:decimal">
        <xs:minInclusive value="0.0"/>
        <xs:maxInclusive value="1.0"/>
      </xs:restriction>
    </xs:simpleType>
    

    The <window>-element represents a window located on a wall in the current room. If the window is connecting two rooms, it is represented once on each wall of each room. See also SymbolInstance for more information.

    Screenshot

    Attribute Description
    symbolInstance The unique identifier of the <symbolInstance> element containing data attached to this window. The symbol instance contains the symbol ID.
    point The index 0-based of the <point> element starting the wall containing the window.
    snappedPosition The corrected relative position of the center of the window on the wall represented by a floating point number between 0.0 and 1.0. This value should be used when drawing an assembled floor plan.
    snappedWidth The corrected width of the window in meters represented by a floating point number. This value should be used when drawing an assembled floor plan.
    snappedOrientation The corrected orientation of the window after the rooms are assembled. Inconsistent window orientations are unified across rooms and may differ from the original orientation. This value should be used when drawing an assembled floor plan. The orientation is a number between 0 and 3 specifying which way the window is facing and if it opens to the left or the right.
    insetZ Floating point number in meters to determine how far the object is into the wall. Positive values show that the object goes away from the wall and into the room. Negative values show that the object goes inside the wall. For example, if you would like to center the object directly onto the wall, you can use -(interior wall thickness/2).

    Furniture

    <?xml version="1.0" encoding="UTF-8"?>
    <furniture
      symbolInstance="F-2-0"
    
      x="0.61257"
      snappedX="-0.00054"
      y="1.21522"
      snappedY="0.78501"
    
      width="1.83600"
      snappedWidth="1.83600"
      depth="0.82584"
      snappedDepth="0.82584"
      angle="3.14173"
    />
    
    <xs:element name="furniture">
      <xs:complexType>
        <xs:attribute name="symbolInstance" type="xs:string" use="required"/>
        <xs:attribute name="snappedX" type="xs:decimal" use="required"/>
        <xs:attribute name="snappedY" type="xs:decimal" use="required"/>
        <xs:attribute name="snappedWidth" type="xs:decimal" use="required"/>
        <xs:attribute name="snappedDepth" type="xs:decimal" use="required"/>
        <xs:attribute name="angle" type="xs:decimal" use="required"/>
      </xs:complexType>
    </xs:element>
    
    <xs:simpleType name="orientation">
      <xs:restriction base="xs:integer">
        <xs:minInclusive value="0"/>
        <xs:maxInclusive value="3"/>
      </xs:restriction>
    </xs:simpleType>
    

    The <furniture>-element represents a piece of furniture in the current room.

    Screenshot

    Attribute Description
    symbolInstance The unique identifier of the <symbolInstance> element containing data attached to this pience of furniture. The symbol instance contains the symbol ID.
    snappedX The horizontal position of the piece of furniture corrected relatively to the center of the floor plan, in meters, as a floating point number. This value should be used when drawing an assembled floor plan.
    snappedY The vertical position of the piece of furniture corrected relatively to the center of the room, in meters, as a floating point number. This value should be used when drawing an assembled floor plan.
    snappedWidth The width of the piece of furniture in meters corrected relatively to the center of the room, represented by a floating point number. This value should be used when drawing an assembled floor plan.
    snappedDepth The depth of the piece of furniture in meters corrected relatively to the center of the room, represented by a floating point number. This value should be used when drawing an assembled floor plan.
    angle The angle of the piece of furniture in radians, as a floating point number.

    Wires

    <?xml version="1.0" encoding="UTF-8"?>
    <wires>
      <wire></wire>
    </wires>
    
    <xs:element name="wires">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="wire" maxOccurs="unbounded"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    

    Each <floor>-element can contain a list of <wire>-elements. A <wire> is not limited to a single room.

    Wire

    <?xml version="1.0" encoding="UTF-8"?>
    <wire>
      <symbolInstance></symbolInstance>
      <first type="point-wallitem" tag="electrical" />
      <point x="3.135146" y="0.648366" />
      <point x="3.950981" y="0.359526" />
      <point x="3.496292" y="-0.150126" />
      <point x="3.945985" y="-0.354645" />
    </wire>
    
    <xs:element name="wire">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="symbolInstance"/>
          <xs:element name="first" type="anchor" minOccurs="0"/>
          <xs:element name="last" type="anchor" minOccurs="0">
          <xs:element name="point" maxOccurs="unbounded">
            <xs:complexType>
              <xs:attribute name="x" type="xs:decimal" use="required"/>
              <xs:attribute name="y" type="xs:decimal" use="required"/>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    
    <xs:complexType name="anchor">
      <xs:attribute name="type" type="anchorType"/>
      <xs:attribute name="tag" type="anchorTag"/>
    </xs:complexType>
    
    <xs:simpleType name="anchorType">
      <xs:list>
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="point-room"/>
            <xs:enumeration value="point-wallitem"/>
            <xs:enumeration value="point-furniture"/>
            <xs:enumeration value="segment-room"/>
            <xs:enumeration value="segment-wallitem"/>
            <xs:enumeration value="segment-furniture"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:list>
    </xs:simpleType>
    
    <xs:simpleType name="anchorTag">
      <xs:list>
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="electrical"/>
            <xs:enumeration value="plumbing"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:list>
    </xs:simpleType>
    

    Screenshot

    For more information on wires, see also SymbolInstance.

    Point

    <?xml version="1.0" encoding="UTF-8"?>
    <wire>
      <symbolInstance></symbolInstance>
      <point x="3.135146" y="0.648366"/>
      <point x="3.950981" y="0.359526"/>
      <point x="3.496292" y="-0.150126"/>
      <point x="3.945985" y="-0.354645"/>
    </wire>
    

    Each <wire>-element has one <point>-element for each point that makes up the wire.

    Attribute Description
    x The horizontal position of the point relatively to the center of the floor, in meters, as a floating point number.
    y The vertical position of the corner relatively to the center of the floor, in meters, as a floating point number.

    First, Last

    The elements <first> and/or <last> are only present if the first/last points of the wire are attached to an anchor.

    <?xml version="1.0" encoding="UTF-8"?>
    <wire>
      <symbolInstance></symbolInstance>
      <first type="point-wallitem" tag="electrical"/>
      <point></point>
      <point></point>
      <point></point>
    </wire>
    

    Each <wire>-element has one <point>-element for each point that makes up the wire.

    Attribute Description
    type The type of anchor the wire point is attached to.

    point-room: the wire is attached to a corner of the room
    point-wallitem: the wire is attached to a point on a wall item
    point-furniture: the wire is attached to a point on a piece of furniture
    segment-room: the wire is attached to a wall of the room
    segment-wallitem: the wire is attached to a segment on a wall item
    segment-furniture: the wire is attached to a segment on a piece of furniture
    tag The tag of the anchor the wire point is attached to. Tags are custom values that can be defined to restrict which anchors. Predefined values include:

    electrical: the wire conducts electricity
    plumbing: the pipe carries water

    Polygons

    <?xml version="1.0" encoding="UTF-8"?>
    <symbolInstance>
      <values></values>
      <polylineData></polylineData>
    </symbolInstance>
    

    Polygon coordinates are stored in a <polylineData>-element under the polygon <symbolInstance>. The <polylineData>-element contains one <polylinePoint> for each point of the polygon, specifying its x and y coordinates.

    For more information on polygons, see also SymbolInstance.

    PolylinePoint

    <?xml version="1.0" encoding="UTF-8"?>
    <polylineData>
      <polylinePoint x="4.135500" y="1.713000"/>
      <polylinePoint x="-4.135500" y="1.713000"/>
      <polylinePoint x="-4.135500" y="-1.286000"/>
      <polylinePoint x="-1.516500" y="-1.286000"/>
      <polylinePoint x="-1.516500" y="-1.713000"/>
      <polylinePoint x="4.135500" y="-1.713000"/>
    </polylineData>
    
    <xs:element name="polylineData">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="polylinePoint" maxOccurs="unbounded">
            <xs:complexType>
              <xs:attribute name="x" type="xs:decimal" use="required"/>
              <xs:attribute name="y" type="xs:decimal" use="required"/>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    
    Attribute Description
    x The horizontal position of the point relatively to the center of the floor, in meters, as a floating point number.
    y The vertical position of the corner relatively to the center of the floor, in meters, as a floating point number.

    SymbolInstance

    Symbol Instances are the primary source for information that the user may have entered in magicplan (e.g. piece of furniture or a door). It contains a list of predefined or custom attributes that holds each value entered by the user (see Values).

    Information pertaining to a plan, a room or a specific point inside a room are currently not stored in a symbol instance but on the element (<plan>, <floorRoom> or <point>) itself.

    <?xml version="1.0" encoding="UTF-8"?>
    <symbolInstance
      id="W-0-1"
      uid="5aec8193.14199fff"
      symbol="hingeddoor"
    >
      <values></values>
    </symbolInstance>
    
    <xs:element name="symbolInstance">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="values" minOccurs="0"/>
          <xs:element name="polylineData" minOccurs="0"/>
        </xs:sequence>
        <xs:attribute name="id" type="xs:string" use="required"/>
        <xs:attribute name="uid" type="xs:string" use="required"/>
        <xs:attribute name="symbol" type="xs:string" use="required"/>
      </xs:complexType>
    </xs:element>
    

    Each <floor> contains a list of <symbolInstance>-elements. Each of those elements describe an instance of a symbol on the current floor along with its parameters.

    Attribute Description
    id An identifier uniquely identifying the current symbol instance so it can be referenced from other elements, namely <door>, <window>, and <furniture>.
    uid Unique id of a symbol instance as assigned by Sensopia in order to track a symbol instance.
    symbol The ID of the symbol represented by the symbol instance. See the list of symbol IDs along with their visual representation. This can also be custom symbol.

    References

    Symbol instances are referenced by <furniture>, <door> and <window> elements. A single <symbolInstance>-element can be referred to by multiple elements when all these elements represent the same object in the plan.

    For instance, a door can be represented by up to three <door>-elements:

    In this case, all three <door> elements will refer to the same <symbolInstance>-element, indicating that they are in fact one and the same.

    Door in first room

    <?xml version="1.0" encoding="UTF-8"?>
    <door
      symbolInstance="W-1-1"
    
      snappedType="2"
    
      point="3"
    
      u="0.68766"
      snappedPosition="0.68850"
    
      width="0.75000"
      snappedWidth="0.75000"
      orientation="0"
      snappedOrientation="0"
    />
    

    Screenshot

    Same door in adjacent room

    <?xml version="1.0" encoding="UTF-8"?>
    <door
      symbolInstance="W-1-1"
    
      snappedType="2"
    
      point="3"
    
      u="0.68766"
      snappedPosition="0.68850"
    
      width="0.75000"
      snappedWidth="0.75000"
      orientation="0"
      snappedOrientation="0"
    />
    

    Screenshot

    Same door in exploded floor plan

    <?xml version="1.0" encoding="UTF-8"?>
    <door
      symbolInstance="W-1-1"
    
      x1="-8.654"
      y1="-0.951"
    
      x2="-7.713"
      y2="-0.951"
    
      width="0.941"
      orientation="3"
    />
    

    Screenshot

    Values

    <?xml version="1.0" encoding="UTF-8"?>
    <values>
      <value key="notes">Example note</value>
    </values>
    
    <xs:element name="values">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="value" maxOccurs="unbounded">
            <xs:complexType>
              <xs:simpleContent>
                <xs:extension base="xs:string">
                  <xs:attribute name="key" type="xs:string" use="required"/>
                </xs:extension>
              </xs:simpleContent>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    

    The <values>-element contains a list of predefined or custom attributes attached to a symbol instance (<symbolInstance>), a point inside a room (<point>), a room (<floorRoom>), a floor or <plan>.

    Attribute Description
    key The unique identifier of the attributes, as defined by magicplan or the symbol xml.

    Common identifiers

    The following list are the most common identifiers you will encounter in a floor plan. For a more comprehensive list, please see the examples below or take a look at Forms.

    Identifier Description
    id The id of an annotation, scoped to the entire plan. The id is shown in the magicplan UI and the PDF. Omitting this field will cause an annotation id to be generated dynamically. You can customize the id for csiitems
    notes user comments
    image[0..n] the file name of an image

    Custom attributes

    <?xml version="1.0" encoding="UTF-8"?>
    <values>
      <value key="5aec8193.14199fff">Example</value>
    </values>
    

    Screenshot

    You can also add custom attributes right from within the magicplan user interface. In this case the keywill be generated by magicplan.

    Wall Items

    Internally magicplan differentiates between wall items and pieces of furniture. Pieces of furniture (chairs, tables, kitchen sink, etc.) are placed freely inside a room while wall items (doors, windows, radiators, etc.) are always placed in relation to a wall.

    In the floor plan (<exploded>) as well as in individual rooms (<floorRoom>) all wall items, except for windows, are expressed as a <door>-element.

    Door

    <?xml version="1.0" encoding="UTF-8"?>
    <floor>
      <symbolInstance
        id="W-0-1"
        uid="5aec8193.14199fff"
        parentUid=""
        symbol="doorhinged"
      >
        <values>
          <value key="displaylabel">above</value>
          <value key="id">2</value>
          <value key="label">Kitchen Door</value>
          <value key="notes">Notes on the door</value>
          <value key="wallItemDistanceToFloor">0.050000</value>
          <value key="wallItemHeight">2.000000</value>
          <value key="wallItemWidth">1.000000</value>
        </values>
      </symbolInstance>
      <floorRoom>
        <door
          symbolInstance="W-0-1"
          
        />
      </floorRoom>
    </floor>
    

    Screenshot

    Window

    <?xml version="1.0" encoding="UTF-8"?>
    <floor>
      <symbolInstance
        id="W-0-0"
        uid="5aec8185.8747ebff"
        parentUid=""
        symbol="windowfrench"
      >
        <values>
          <value key="displaylabel">above</value>
          <value key="id">7</value>
          <value key="label">Rear Window</value>
          <value key="notes">Notes on the window</value>
          <value key="wallItemDistanceToFloor">1.000000</value>
          <value key="wallItemHeight">1.200000</value>
          <value key="wallItemWidth">1.000000</value>
        </values>
      </symbolInstance>
      <floorRoom>
        <window
          symbolInstance="W-0-0"
          
        />
      </floorRoom>
    </floor>
    

    Screenshot

    Radiator

    <?xml version="1.0" encoding="UTF-8"?>
    <floor>
      <symbolInstance
        id="W-1-0"
        uid="5af9a5e3.c1b5d7ff"
        parentUid=""
        symbol="radiatorwater"
      >
        <values>
          <value key="displaylabel">above</value>
          <value key="id">4</value>
          <value key="label">Radiator</value>
          <value key="notes">Notes on the radiator</value>
          <value key="wallItemDistanceToFloor">0.200000</value>
          <value key="wallItemHeight">0.600000</value>
          <value key="wallItemWidth">0.800000</value>
        </values>
      </symbolInstance>
      <floorRoom>
        <door
          symbolInstance="W-1-0"
          
        />
      </floorRoom>
    </floor>
    

    Screenshot

    Furniture

    <?xml version="1.0" encoding="UTF-8"?>
    <floor>
      <symbolInstance
        id="F-0-0"
        uid="5aec8337.df981fff"
        parentUid=""
        symbol="chair"
      >
        <values>
          <value key="height">2.000000</value>
          <value key="id">1</value>
          <value key="image[0]">img0.png</value>
          <value key="notes">These are notes</value>
          <value key="volumeUnit">m3</value>
        </values>
      </symbolInstance>
      <floorRoom>
        <furniture
          symbolInstance="F-0-0"
          
        />
      </floorRoom>
    </floor>
    

    Screenshot

    Floor

    <?xml version="1.0" encoding="UTF-8"?>
    <floor>
      <symbolInstance
        id="floor"
        uid="5aec7942.84ba6fff"
        symbol="floor"
      >
        <values>
          <value key="notes">These are notes</value>
        </values>
      </symbolInstance>
    </floor>
    

    Screenshot

    Plan

    <?xml version="1.0" encoding="UTF-8"?>
    <plan>
      <values>
        <value key="date">2018-05-04</value>
      </values>
    </plan>
    

    Screenshot

    Room

    <?xml version="1.0" encoding="UTF-8"?>
    <floorRoom>
      <label>Kitchenette</label>
      <values>
        <value key="notes">Notes here</value>
      </values>
    </floorRoom>
    

    Screenshot

    Wall

    <?xml version="1.0" encoding="UTF-8"?>
    <floorRoom>
      <point snappedX="-1.31000" snappedY="1.31000">
        <values>
          <value key="id">3</value>
          <value key="image[0]">img1.png</value>
          <value key="notes">Notes</value>
        </values>
      </point>
      <point/>
      <point/>
      <point/>
    </floorRoom>
    

    The information are stored in the starting point of the corresponding wall.

    Screenshot

    Wire

    <?xml version="1.0" encoding="UTF-8"?>
    <floor>
      <wires>
        <wire>
          <symbolInstance
            uid="5b64c0d2.53fccbff"
            symbol="wire220"
          >
            <values>
              <value key="id">8</value>
              <value key="amperage">15</value>
              <value key="circuitnb">12</value>
              <value key="wire.color">29d000ff</value>
              <value key="wire.line">2</value>
              <value key="wire.linetype">1</value>
              <value key="wire.thickness">0.030000</value>
            </values>
          </symbolInstance>
          <first></first>
          <point></point>
        </wire>
      </wires>
    </floor>
    

    Screenshot

    Polygon

    <?xml version="1.0" encoding="UTF-8"?>
    <floor>
      <symbolInstance
        id="F-0"
        uid="5b64bc82.d160b7ff"
        symbol="buildinglayout"
      >
        <values>
          <value key="polyline.fill">1</value>
          <value key="polyline.fill.alpha">0.2</value>
          <value key="polyline.fill.color">00000033</value>
          <value key="polyline.showdimensions">1</value>
          <value key="polyline.stroke">1</value>
          <value key="polyline.stroke.color">000000FF</value>
          <value key="polyline.stroke.thickness">0.1</value>
        </values>
        <polylineData></polylineData>
      </symbolInstance>
    </floor>
    

    Screenshot

    Symbols XML

    Symbols

    <?xml version="1.0" encoding="UTF-8"?>
    <symbols>
      <category></category>
      <symbol></symbol>
      <form></form>
    </symbols>
    
    <xs:element name="symbols">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="category" maxOccurs="unbounded"/>
          <xs:element name="symbol" maxOccurs="unbounded"/>
          <xs:element name="form" minOccurs="0" maxOccurs="unbounded"/>
          <xs:element name="category" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    

    A set of symbol files ships with MagicPlan and defines its standard object library. Custom symbol files can be added based on the workgroup a user is in.

    At the root of the symbol XML file is a <symbols>-element. This element contains a list of <symbol>-elements representing objects that can be manipulated by MagicPlan.

    Symbol

    <?xml version="1.0" encoding="UTF-8"?>
    <symbol
      id="plumbing.sink"
      type="room"
    
      sizeX="0.5"
      sizeY="0.5"
      sizeZ="1.0"
    
      minSizeX="0.5"
      minSizeY="0.5"
      minSizeZ="1.0"
      maxSizeX="0.5"
      maxSizeY="0.5"
      maxSizeZ="1.0"
      aspectRatio="1"
      duplicatable="1"
    >
      <parent></parent>
      <name></name>
      <description></description>
      <image></image>
      <defaultValues></defaultValues>
    </symbol>
    
    <xs:element name="symbols">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="parent" maxOccurs="unbounded"/>
          <xs:element name="room" minOccurs="0" maxOccurs="unbounded"/>
          <xs:element name="name" minOccurs="0"/>
          <xs:element name="description" minOccurs="0"/>
          <xs:element name="image" minOccurs="0" maxOccurs="unbounded"/>
          <xs:element name="defaultvalues" minOccurs="0"/>
          <xs:element name="subItem" minOccurs="0"/>
          <xs:element name="link" minOccurs="0"/>
        </xs:sequence>
    
        <xs:attribute name="id" type="xs:string" use="required"/>
        <xs:attribute name="type" type="symbolType" use="required"/>
    
        <xs:attribute name="sizeX" type="xs:decimal" use="required"/>
        <xs:attribute name="sizeY" type="xs:decimal" use="required"/>
        <xs:attribute name="sizeZ" type="xs:decimal" use="required"/>
    
        <xs:attribute name="minSizeX" type="xs:decimal"/>
        <xs:attribute name="minSizeY" type="xs:decimal"/>
        <xs:attribute name="minSizeZ" type="xs:decimal"/>
        <xs:attribute name="maxSizeX" type="xs:decimal"/>
        <xs:attribute name="maxSizeY" type="xs:decimal"/>
        <xs:attribute name="maxSizeZ" type="xs:decimal"/>
        <xs:attribute name="aspectRatio" type="xs:boolean"/>
        <xs:attribute name="duplicatable" type="xs:boolean"/>
    
        <xs:attribute name="stopsWall" type="xs:boolean"/>
        <xs:attribute name="insetHighX" type="xs:decimal"/>
        <xs:attribute name="insetHighY" type="xs:decimal"/>
    
        <xs:attribute name="doorType">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:pattern value="inside|outside|both"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
        <xs:attribute name="sharedDoor" type="xs:boolean"/>
      </xs:complexType>
    </xs:element>
    
    <xs:simpleType name="symbolType">
      <xs:list>
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="room"/>
            <xs:enumeration value="floor"/>
            <xs:enumeration value="plan"/>
            <xs:enumeration value="landsurvey"/>
            <xs:enumeration value="wall"/>
            <xs:enumeration value="wire"/>
            <xs:enumeration value="roll"/>
            <xs:enumeration value="catalog"/>
            <xs:enumeration value="tiles"/>
            <xs:enumeration value="polygon"/>
            <xs:enumeration value="moduleTask"/>
            <xs:enumeration value="all"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:list>
    </xs:simpleType>
    

    The <symbol>-element represents any object that has a visual representation and that can be instantiated. For example, symbols can be inserted into a room, attached to a wall or used as an item for an estimate.

    Screenshot

    Attribute Description
    id The unique identifier for the object. This identifier needs to be unique across all symbol files.
    type Defines which type the symbol is. A symbol can be of many types separated with spaces. For a list of available types, please see Types.
    sizeX The dimensions of the object in meters. When drawing the symbol on the floor plan, the view box of the SVG image is stretched to fit the sizeX, sizeY rectangle exactly.
    sizeY The dimensions of the object in meters. When drawing the symbol on the floor plan, the view box of the SVG image is stretched to fit the sizeX, sizeY rectangle exactly.
    sizeZ The dimensions of the object in meters. When drawing the symbol on the floor plan, the view box of the SVG image is stretched to fit the sizeX, sizeY rectangle exactly.

    Optional attributes

    Attribute Description
    minSizeX The minimum dimensions of the object in meters. The user cannot resize the object to a smaller size.
    minSizeY The minimum dimensions of the object in meters. The user cannot resize the object to a smaller size.
    minSizeZ The minimum dimensions of the object in meters. The user cannot resize the object to a smaller size.
    maxSizeX The maximum dimensions of the object in meters. The user cannot resize the object to a larger size.
    maxSizeY The maximum dimensions of the object in meters. The user cannot resize the object to a larger size.
    maxSizeZ The maximum dimensions of the object in meters. The user cannot resize the object to a larger size.
    aspectRatio 0: Do not lock the x, y aspect ratio. [default]
    1: Lock the x, y aspect ratio.
    duplicatable 0: The object cannot be duplicated along a grid. [default]
    1: The object can be duplicated multiple times along a x, y grid.

    Name

    <?xml version="1.0" encoding="UTF-8"?>
    <name language="en">Hinged Door</name>
    
    <xs:element name="name">
      <xs:complexType>
        <xs:simpleContent>
          <xs:extension base="xs:string">
            <xs:attribute name="language" type="xs:string" use="required"/>
          </xs:extension>
        </xs:simpleContent>
      </xs:complexType>
    </xs:element>
    

    Screenshot

    A localized name of the <symbol>. If no name is specified for a given language, then the English name is used. If no English name is specified, then the first name in the list is used instead.

    Attribute Description
    language The 2-letter ISO language code of the localized name.

    Description

    <?xml version="1.0" encoding="UTF-8"?>
    <description language="en">A hinged door</description>
    
    <xs:element name="description">
      <xs:complexType>
        <xs:simpleContent>
          <xs:extension base="xs:string">
            <xs:attribute name="language" type="xs:string" use="required"/>
          </xs:extension>
        </xs:simpleContent>
      </xs:complexType>
    </xs:element>
    

    Screenshot

    A localized description of the <symbol>. A description is typically longer and more detailed than a name. If no description is specified for a given language, then the English description is used. If no English description is specified, then the first description in the list is used instead.

    Attribute Description
    language The 2-letter ISO language code of the localized description.

    Image

    See Image.

    Room

    <?xml version="1.0" encoding="UTF-8"?>
    <room type="Living Room"/>
    <room type="Bedroom"/>
    
    <xs:element name="room">
      <xs:complexType>
        <xs:attribute name="type" type="xs:string" use="required"/>
        <xs:attribute name="count" type="xs:integer"/>
      </xs:complexType>
    </xs:element>
    

    The <room>-element specifies what type of room the symbol is usually used in.

    Attribute Description
    type The type of room the symbol applies to.

    Screenshot

    Types

    A symbol can be of multiple types. Depending on the type, some new attributes might become available, e.g. Wall items. Depending on the context (room, floor, etc.) and the type of the symbol, some symbols might not show up in the menu.

    Although a symbol can be of multiple types at once, for the best user experience there are some configurations that work best. For example, wall items (i.e. symbols with the type wall) should not be used in conjuction with other symbol types.

    Room

    <?xml version="1.0" encoding="UTF-8"?>
    <symbol
      type="room"
      
    >
      <parent></parent>
      <name></name>
      <description></description>
      <image></image>
      <defaultValues></defaultValues>
    </symbol>
    

    The symbol can be inserted into a room.

    Screenshot

    Floor

    <?xml version="1.0" encoding="UTF-8"?>
    <symbol
      type="floor"
      
    >
      <parent></parent>
      <name></name>
      <description></description>
      <image></image>
      <defaultValues></defaultValues>
    </symbol>
    

    The symbol can be inserted at the floor level, e.g. a tree or a car.

    Screenshot

    Land survey

    <?xml version="1.0" encoding="UTF-8"?>
    <symbol
      type="landsurvey"
      
    >
      <parent></parent>
      <name></name>
      <description></description>
      <image></image>
      <defaultValues></defaultValues>
    </symbol>
    

    The symbol can be inserted into a land survey (see also Code List). For the symbol to appear in the menu, the floor "land survey" needs to be opened.

    Screenshot

    Wall

    <?xml version="1.0" encoding="UTF-8"?>
    <symbol
      type="wall"
      
    >
      <parent></parent>
      <name></name>
      <description></description>
      <image></image>
      <defaultValues></defaultValues>
    </symbol>
    

    The symbol is a wall item and must be attached to a wall.

    Screenshot

    Optional attributes

    Attribute Description
    stopsWall 0: The wall item does not interrupt the wall it is attached to (door, window).
    1: The wall item interrupts the wall it is attached to (electrical symbol). [default]
    insetHighX A translation in meters in a direction parallel to the wall. Positive values move to the right when facing the inside of the room.
    insetHighY A translation in meters in a direction perpendicular to the wall. A value of 0 places the object in the mid-point of the wall. Positive values move towards the inside of the room.

    Common keys for default values

    <?xml version="1.0" encoding="UTF-8"?>
    <symbol type="wall">
      <defaultvalues>
        <value key="wallItemDistanceToFloor">1.0</value>
      </defaultvalues>
    </symbol>
    

    When creating a symbol of the type wall you can define some default values in order to change the appearance on the floor plan. See also default values.

    Key Description
    wallItemDistanceToFloor This attribute defines the distance between the floor and the bottom of the wall item. It is therefore an essential piece of information when rendering the floor plan in 3D or computing additional values for each room.

    Wire

    <?xml version="1.0" encoding="UTF-8"?>
    <symbol
      type="wire"
      
    >
      <parent></parent>
      <name></name>
      <description></description>
      <image></image>
      <defaultValues></defaultValues>
    </symbol>
    

    The symbol is a polyline that can span multiple rooms, e.g. electricity and plumbing. It can be added on the floor level.

    Screenshot

    Common keys for default values

    <?xml version="1.0" encoding="UTF-8"?>
    <symbol type="wire">
      <defaultvalues>
        <value key="type">1</value>
        <value key="color">CF142BFF</value>
        <value key="thickness">0.05</value>
      </defaultvalues>
    </symbol>
    

    When creating a symbol of the type wire you can define some default values in order to change the appearance on the floor plan. See also default values.

    Key Description
    type Specifies the type of line used to draw the wire. Possible values are 1 (Solid) and 2 (Dashed). Default is 1.
    color The color of the wire in RGBA (red, green, blue, alpha) hexadecimal. Default is opaque red CF142BFF.
    thickness The width of the wire in meters. Must be between 0.005 and 0.5. Default value is 0.05.

    Polygon

    <?xml version="1.0" encoding="UTF-8"?>
    <symbol
      type="polygon"
      
    >
      <parent></parent>
      <name></name>
      <description></description>
      <image></image>
      <defaultValues></defaultValues>
    </symbol>
    

    The symbol is a closed polygon consisting in a series of connected straight lines. There are most useful when performing land surveys, e.g. side walks etc.

    Screenshot

    Image

    <xs:element name="image">
      <xs:complexType>
        <xs:sequence>
          <xs:element ref="svg:svg" minOccurs="0"/>
        </xs:sequence>
    
        <xs:attribute name="id" type="xs:string"/>
        <xs:attribute name="type" type="availableImageTypes"/>
        <xs:attribute name="x" type="xs:decimal"/>
        <xs:attribute name="y" type="xs:decimal"/>
        <xs:attribute name="src" type="xs:string"/>
        <xs:attribute name="sizeX" type="xs:decimal"/>
        <xs:attribute name="sizeY" type="xs:decimal"/>
        <xs:attribute name="minSizeX" type="xs:decimal"/>
        <xs:attribute name="minSizeY" type="xs:decimal"/>
        <xs:attribute name="minSizeZ" type="xs:decimal"/>
        <xs:attribute name="maxSizeX" type="xs:decimal"/>
        <xs:attribute name="maxSizeY" type="xs:decimal"/>
        <xs:attribute name="maxSizeZ" type="xs:decimal"/>
        <xs:attribute name="alignX" type="xs:decimal"/>
        <xs:attribute name="alignY" type="xs:decimal"/>
        <xs:attribute name="alignZ" type="xs:decimal"/>
        <xs:attribute name="repeatX" type="xs:decimal"/>
        <xs:attribute name="repeatY" type="xs:decimal"/>
        <xs:attribute name="repeatZ" type="xs:decimal"/>
        <xs:attribute name="scaleX" type="xs:decimal"/>
        <xs:attribute name="scaleY" type="xs:decimal"/>
        <xs:attribute name="scaleZ" type="xs:decimal"/>
        <xs:attribute name="stretchX" type="xs:decimal"/>
        <xs:attribute name="stretchY" type="xs:decimal"/>
        <xs:attribute name="stretchZ" type="xs:decimal"/>
        <xs:attribute name="translateX" type="xs:decimal"/>
        <xs:attribute name="translateY" type="xs:decimal"/>
        <xs:attribute name="translateZ" type="xs:decimal"/>
      </xs:complexType>
    </xs:element>
    
    <xs:simpleType name="availableImageTypes">
      <xs:list>
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:enumeration value="menu"/>
            <xs:enumeration value="schematic"/>
            <xs:enumeration value="realistic"/>
            <xs:enumeration value="elevation"/>
            <xs:enumeration value="elevation-left"/>
            <xs:enumeration value="elevation-right"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:list>
    </xs:simpleType>
    

    With SVG

    <?xml version="1.0" encoding="UTF-8"?>
    <image
      id="Video"
      type="realistic schematic"
      x="0.0"
      y="0.0"
      sizeX="1.0"
      sizeY="1.0"
    >
      <svg></svg>
    </image>
    
    <!-- see above -->
    

    With SRC

    <?xml version="1.0" encoding="UTF-8"?>
    <image
      id="Video"
      type="realistic schematic"
      x="0.0"
      y="0.0"
      sizeX="1.0"
      sizeY="1.0"
      src="../example.png"
    />
    
    <!-- see above -->
    

    The <image>-element represents the image used for the current symbol. A symbol can have multiple images. If an image of type menu is specified, it is used to represent the symbol in a menu.

    All attributes are optional.

    Attribute Description
    id The unique identifier of the image. This identifier is essentially used to target text at the image boundaries.
    type The type of image. An image can have multiple types separated with spaces.
    x The position of the image inside the bounding object box. [default: 0]
    y The position of the image inside the bounding object box. [default: 0]
    src The relative path of a bitmap file (PNG or JPG).
    sizeX The size of the image. [default: same as symbol]
    sizeY The size of the image. [default: same as symbol]
    minSizeX The minimum dimensions of the image in meters. The user cannot resize the image to a smaller size.
    minSizeY The minimum dimensions of the image in meters. The user cannot resize the image to a smaller size.
    minSizeZ The minimum dimensions of the image in meters. The user cannot resize the image to a smaller size.
    maxSizeX The maximum dimensions of the image in meters. The user cannot resize the image to a larger size.
    maxSizeY The maximum dimensions of the image in meters. The user cannot resize the image to a larger size.
    maxSizeZ The maximum dimensions of the image in meters. The user cannot resize the image to a larger size.
    alignX Specifies if the image is aligned with the left (X) or top (Y) of the symbol area (0.0), or with the right (X) or bottom (Y) of the symbol (1.0). Values between 0.0 and 1.0 align the image proportionally in-between, with 0.5 centering it.
    alignY Specifies if the image is aligned with the left (X) or top (Y) of the symbol area (0.0), or with the right (X) or bottom (Y) of the symbol (1.0). Values between 0.0 and 1.0 align the image proportionally in-between, with 0.5 centering it.
    alignZ Specifies if the image is aligned with the left (X) or top (Y) of the symbol area (0.0), or with the right (X) or bottom (Y) of the symbol (1.0). Values between 0.0 and 1.0 align the image proportionally in-between, with 0.5 centering it.
    repeatX The number of times the image is repeated in any direction [default: 0.0]. As the image is stretched, more repetitions are added instead of stretching the image all the way.
    repeatY The number of times the image is repeated in any direction [default: 0.0]. As the image is stretched, more repetitions are added instead of stretching the image all the way.
    repeatZ The number of times the image is repeated in any direction [default: 0.0]. As the image is stretched, more repetitions are added instead of stretching the image all the way.
    scaleX Specifies how much the images scales relatively to the symbol when its size changes [default 1.0]. A value of 1.0 scales the image proportionally with the symbol.
    scaleY Specifies how much the images scales relatively to the symbol when its size changes [default 1.0]. A value of 1.0 scales the image proportionally with the symbol.
    scaleZ Specifies how much the images scales relatively to the symbol when its size changes [default 1.0]. A value of 1.0 scales the image proportionally with the symbol.
    stretchX When repeating an image in a given direction (repeatXYZ > 0.0), should the image stretch before there is enough room to repeat it [default 0.0]. A value of 1.0 stretches the image proportionally with the symbol.
    stretchY When repeating an image in a given direction (repeatXYZ > 0.0), should the image stretch before there is enough room to repeat it [default 0.0]. A value of 1.0 stretches the image proportionally with the symbol.
    stretchZ When repeating an image in a given direction (repeatXYZ > 0.0), should the image stretch before there is enough room to repeat it [default 0.0]. A value of 1.0 stretches the image proportionally with the symbol.
    translateX If the displacement of this image relatively to the position of the previous image. Only has an effect when there are multiple images.
    translateY If the displacement of this image relatively to the position of the previous image. Only has an effect when there are multiple images.
    translateZ If the displacement of this image relatively to the position of the previous image. Only has an effect when there are multiple images.

    SVG vs. Bitmap

    The preferred way to provide an image is to use an SVG. When using SVG you provide a the image in a vector format which allows the image to scale without loss of quality. In addition, some of the export formats do not support bitmaps.

    Bitmaps are generally used for true images. For example when showing an actual image of the carpet in an estimate or for menus.

    Menu

    <?xml version="1.0" encoding="UTF-8"?>
    <image
      type="menu"
      
    >
      <svg></svg>
    </image>
    

    Use the image type menu if displaying the object in a menu. If not specified, other available images are used.

    Screenshot Screenshot

    Schematic

    <?xml version="1.0" encoding="UTF-8"?>
    <image
      type="schematic"
      
    >
      <svg></svg>
    </image>
    

    Use the image type schematic if the image is a schematic representation of the object, typically a simplified vector drawing.

    Screenshot

    Elevation

    <?xml version="1.0" encoding="UTF-8"?>
    <image
      type="elevation"
      
    >
      <svg></svg>
    </image>
    

    Use the image type elevation to represent the elevation view of an object as seen from the front when facing the wall holding the object.

    Screenshot

    Left and Right

    <?xml version="1.0" encoding="UTF-8"?>
    <image
      type="elevation-left"
      
    >
      <svg></svg>
    </image>
    
    <?xml version="1.0" encoding="UTF-8"?>
    <image
      type="elevation-right"
      
    >
      <svg></svg>
    </image>
    

    For a more control you may also add the image type elevation-left or elevation-right to represent the elevation view of an object as seen from the left or right.

    If you only provide one view of the object, magicplan tries to infer the corresponding view by flipping the image accordingly. For example, if you only provide elevation-left and omit elevation-right, magicplan will automatically use the image from elevation-left and flip it.

    Screenshot

    Realistic

    <?xml version="1.0" encoding="UTF-8"?>
    <image
      type="realistic"
      
    >
      <svg></svg>
    </image>
    

    Use the image type realistic if the image is a realistic representation of the object, typically a picture.

    Grouping

    Usually each catalog of symbols will have one root <category> under which all the other <symbols> are grouped.

    Category

    <?xml version="1.0" encoding="UTF-8"?>
    <category>
      <name></name>
      <description></description>
      <image></image>
    </category>
    
    <xs:element name="category">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="name" minOccurs="0"/>
          <xs:element name="description" minOccurs="0"/>
          <xs:element name="image" minOccurs="0"/>
        </xs:sequence>
        <xs:attribute name="id" type="xs:string" use="required"/>
        <xs:attribute name="priority" type="xs:integer"/>
      </xs:complexType>
    </xs:element>
    

    The <category>-element is used to group <symbol>s together.

    Screenshot

    There are two different kind of categories:

    Named browsable category

    <?xml version="1.0" encoding="UTF-8"?>
    <category id="acme" priority="100">
      <name language="en">ACME Inc</name>
      <image></image>
    </category>
    
    <category id="acme.appliances" priority="100">
      <name language="en">Appliances</name>
      <parent id="acme"/>
      <image></image>
    </category>
    
    <xs:element name="name">
      <xs:complexType>
        <xs:simpleContent>
          <xs:extension base="xs:string">
            <xs:attribute name="language" type="xs:string" use="required"/>
          </xs:extension>
        </xs:simpleContent>
      </xs:complexType>
    </xs:element>
    

    Named categories are browsable categories used to create the object menu hierarchy. The order in which those categories are displayed in the menu depends on their priority. Categories with a low priority-number will be shown before categories that have a higher priority-number.

    Empty categories will be hidden from the menu. Categories are only visible if they have at least one symbol that can be added in the current context, i.e. in a room, in a floor etc.

    Screenshot

    Unnamed abstract category

    <?xml version="1.0" encoding="UTF-8"?>
    <category id="plumbing"/>
    

    Unnamed categories are abstract categories used to assign common properties (such as forms) to families of symbols.

    Such a category can also be used to group symbols that are interchangable in the floor plan.

    Screenshot

    Parent

    <?xml version="1.0" encoding="UTF-8"?>
    <category id="acme.windows">
      <name language="en">Windows</name>
    </category>
    
    <symbol>
      <name language="en">Skylight</name>
      <parent id="acme.windows"/>
    </symbol>
    
    <symbol type="wall">
      <name language="en">Casement Window</name>
      <parent id="acme.windows"/>
      <parent id="wallitems"/>
    </symbol>
    
    <xs:element name="parent">
      <xs:complexType>
        <xs:attribute name="id" type="xs:string" use="required"/>
      </xs:complexType>
    </xs:element>
    

    Each <symbol>-element may contain a <parent>-element to refer to a <category>-element containing the current symbol. A symbol can belong to more than one category, and inherits all forms that are attached to these categories.

    Attribute Description
    id The unique identifier of the <category>.

    Screenshot

    Default Values

    <?xml version="1.0" encoding="UTF-8"?>
    <defaultvalues>
      <value key="price">522.13</value>
      <value key="pricingModel">surface</value>
      <value key="surfaceReference">compute</value>
      <value key="surfaceReferenceGround">1</value>
      <value key="surfaceUnit">m2</value>
      <value key="trade">tiling</value>
    </defaultvalues>
    
    <xs:element name="defaultvalues">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="value" maxOccurs="unbounded">
            <xs:complexType>
              <xs:simpleContent>
                <xs:extension base="xs:string">
                  <xs:attribute name="key" type="xs:string" use="required"/>
                </xs:extension>
              </xs:simpleContent>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
      </xs:complexType>
    </xs:element>
    

    The <defaultvalues>-element contains a list of <value>-elements. Those <value>-elements are used to specify default values of object definitions or actual values of object instances.

    For a list of available keys, see Code Lists.

    Attribute Description
    key The unique identifier of the value, as specified by the field ID of the corresponding form.

    Screenshot

    Forms

    <?xml version="1.0" encoding="UTF-8"?>
    <form
      id="roof"
    >
      <category id="structure"/>
      <field></field>
    </form>
    
    <xs:element name="form">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="symbol" minOccurs="0" maxOccurs="unbounded"/>
          <xs:element name="category" minOccurs="0" maxOccurs="unbounded"/>
          <xs:element name="field" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:attribute name="id" type="xs:string" use="required"/>
      </xs:complexType>
    </xs:element>
    

    A <form>-element contains a series of <field>-elements. Each <form> can be assigned to one or more symbols and to one or more categories.

    Forms are sorted dynamically by alphabetical order of their IDs when creating the combined list of attributes for a specific object.

    Attribute Description
    id The unique identifier of the form. This identifier needs to be unique across all symbol files.

    Screenshot

    Attaching to symbols

    There are two options to attach a form to a symbol:

    Symbol

    <?xml version="1.0" encoding="UTF-8"?>
    <form id="poolOptions">
      <symbol id="pool1"/>
      <symbol id="pool2"/>
    </form>
    
    <xs:element name="symbol">
      <xs:complexType>
        <xs:attribute name="id" type="xs:string" use="required"/>
      </xs:complexType>
    </xs:element>
    

    A symbol that uses the current form. Fields of the form will appear when editing an instance of this symbol.

    In this example the symbols pool1 and pool2 will use the fields defined in the form.

    Category

    <?xml version="1.0" encoding="UTF-8"?>
    <form id="roof">
      <category id="structure"/>
    </form>
    
    <xs:element name="category">
      <xs:complexType>
        <xs:attribute name="id" type="xs:string" use="required"/>
      </xs:complexType>
    </xs:element>
    

    A category containing symbols that should use the current form. Fields of the form will appear when editing an instance of any object in the category.

    As a best practice you should use abstract categories when attaching a form to a symbol via a category. If you use named categories instead, the symbol might loose the fields attached to it once the user moves the symbol to a different category in the magicplan UI.

    In this example the symbols belonging to the category structure will use the fields defined in the form.

    Field

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roofCondition"
      type="list"
    >
      <name language="en">Roof Condition</name>
      <option value="New"/>
      <option value="Relatively New"/>
      <option value="Signs of Wear"/>
      <option value="Significant Wear"/>
      <option value="Requires Resurfacing"/>
    </field>
    
    <xs:element name="field">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="name" type="localizedString" minOccurs="0"/>
          <xs:element name="description" type="localizedString" minOccurs="0"/>
          <xs:element name="option" minOccurs="0" maxOccurs="unbounded">
            <xs:complexType>
              <xs:sequence>
                <xs:element name="name" type="localizedString" minOccurs="0"/>
                <xs:element name="description" type="localizedString" minOccurs="0"/>
                <xs:element name="image" type="image" minOccurs="0"/>
              </xs:sequence>
              <xs:attribute name="value" type="xs:string" use="required"/>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
        <xs:attribute name="id" type="xs:string"/>
        <xs:attribute name="type">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:enumeration value="bool"/>
              <xs:enumeration value="text"/>
              <xs:enumeration value="multitext"/>
              <xs:enumeration value="list"/>
              <xs:enumeration value="distance"/>
              <xs:enumeration value="date"/>
              <xs:enumeration value="time"/>
              <xs:enumeration value="image"/>
              <xs:enumeration value="svg"/>
              <xs:enumeration value="color"/>
              <xs:enumeration value="label"/>
              <xs:enumeration value="float"/>
              <xs:enumeration value="integer"/>
              <xs:enumeration value="separator"/>
              <xs:enumeration value="button"/>
              <xs:enumeration value="slider"/>
              <xs:enumeration value="disclosure"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
        <xs:attribute name="default" type="xs:string"/>
        <xs:attribute name="annotation">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:enumeration value="always"/>
              <xs:enumeration value="never"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
        <xs:attribute name="if" type="xs:string"/>
        <xs:attribute name="min" type="xs:decimal"/>
        <xs:attribute name="max" type="xs:decimal"/>
        <xs:attribute name="multiplicity">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:enumeration value="+"/>
              <xs:enumeration value="*"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:attribute>
      </xs:complexType>
    </xs:element>
    
    <xs:complexType name="localizedString">
      <xs:simpleContent>
        <xs:extension base="xs:string">
          <xs:attribute name="language" type="xs:string" use="required"/>
        </xs:extension>
      </xs:simpleContent>
    </xs:complexType>
    

    A <field>-element that is part of a <form>-element. It is used in magicplan to customize the fields when editing a symbol.

    Attribute Description
    id The unique identifier of the field. This identifier needs to be unique across all symbol files.
    type The type of field. For a list of available types see exampels below.
    default Default value for the field. See also default values if you need to define default values on the symbol instead of the field.
    annotation Determines whether this field generates a foot note annotation in floor plan reports. By default, a foot note is only generated if the value contained in the form instance is different than the field default value. This behavior can be overridden in two ways:
    always: This field always generates an foot note, even if its value is equal to the default value.
    never: This field never generates a foot note, no matter the value.
    if Adds a condition to the field which determines when the field should be shown. See also conditional fields for more information.

    Name

    <?xml version="1.0" encoding="UTF-8"?>
    <name language="en">Roof Condition</name>
    
    <xs:element name="name">
      <xs:complexType>
        <xs:simpleContent>
          <xs:extension base="xs:string">
            <xs:attribute name="language" type="xs:string" use="required"/>
          </xs:extension>
        </xs:simpleContent>
      </xs:complexType>
    </xs:element>
    

    Each field needs a label which is shown in the user interface. The only exception is the separator which is only used to separate fields in a form.

    If no name is specified for a given language, then the English name is used. If no English name is specified, then the first name in the list is used instead.

    Attribute Description
    language The 2-letter ISO language code of the localized name.

    Screenshot

    Description

    <?xml version="1.0" encoding="UTF-8"?>
    <description language="en">Please make a choice.</description>
    
    <xs:element name="description">
      <xs:complexType>
        <xs:simpleContent>
          <xs:extension base="xs:string">
            <xs:attribute name="language" type="xs:string" use="required"/>
          </xs:extension>
        </xs:simpleContent>
      </xs:complexType>
    </xs:element>
    

    A localized description of the <field>. A description is typically longer and more detailed than a name. If no description is specified for a given language, then the English description is used. If no English description is specified, then the first description in the list is used instead.

    Attribute Description
    language The 2-letter ISO language code of the localized description.

    Image

    See Image.

    Conditional fields

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roof.isDamaged"
      type="bool"
    >
      <name language="en">Roof damaged</name>
    </field>
    <field
      id="roof.repair"
      type="bool"
      if="roof.isDamaged"
    >
      <name language="en">Repair</name>
    </field>
    

    Sometimes you may want to show or hide fields depending on values of other fields. You can use the if attribute of the symbol to provide a conditional expression referencing other field ids which will be tested.

    In addition to the example more complex conditions are possible. You can use logical operators like &&, || or comparison operators like < or >. Operators can be grouped using ( ).

    Type Bool

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roof.debris"
      type="bool"
    >
      <name language="en">Debris on Roof</name>
    </field>
    

    Screenshot

    Depending on the default value of the field, the value entered by the user might not be exported in the floor plan xml.

    Type List

    A finite list of options to choose from editable in a drop down list.

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roof.condition"
      type="list"
    >
      <name language="en">Roof Condition</name>
      <option value="new">
        <name language="en">New</name>
      </option>
      <option value="relatively_new"/>
        <name language="en">Relatively New</name>
      </option>
      <option value="signs_of_wear"/>
        <name language="en">Signs of Wear</name>
      </option>
      <option value="significant_wear"/>
        <name language="en">Significant Wear</name>
      </option>
      <option value="requires_resurfacing"/>
        <name language="en">Requires Resurfacing</name>
      </option>
    </field>
    

    Screenshot

    Options

    <?xml version="1.0" encoding="UTF-8"?>
    <option value="unassigned">
      <name language="en">Unassigned</name>
    </option>
    <option value="assigned">
      <name language="en">Assigned</name>
    </option>
    <option value="in_progress">
      <name language="en">In Progress</name>
    </option>
    <option value="completed">
      <name language="en">Completed</name>
    </option>
    
    <xs:element name="option">
      <xs:complexType>
        <xs:sequence>
          <xs:element name="name" minOccurs="0">
            <xs:complexType>
              <xs:simpleContent>
                <xs:extension base="xs:string">
                  <xs:attribute name="language" type="xs:string" use="required"/>
                </xs:extension>
              </xs:simpleContent>
            </xs:complexType>
          </xs:element>
        </xs:sequence>
        <xs:attribute name="value" type="xs:string" use="required"/>
      </xs:complexType>
    </xs:element>
    

    An option that is part of a list field. Values can have names, descriptions and images. If no name is specicied, than the value is displayed for all languages.

    Attribute Description
    value The value of the option that is stored in the symbol instance. This identifier only needs to be unique within the current field.

    Screenshot

    with images

    <?xml version="1.0" encoding="UTF-8"?>
    <option value="option_a">
      <name language="en">Checkered</name>
      <image src="checkered.jpg" />
    </option>
    <option value="option_b">
      <name language="en">Lines</name>
      <image src="lines.jpg" />
    </option>
    

    Type Text

    A single line of text editable in a one-line text box.

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roof.example"
      type="text"
    >
      <name language="en">Example</name>
    </field>
    

    Screenshot

    Type Multiline Text

    One or more lines of text editable in a large text box.

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roof.example"
      type="multitext"
    >
      <name language="en">Example</name>
    </field>
    

    Screenshot

    Type Distance

    A distance in meters that can be entered using a numeric keyboard or a laser meter.

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roof.example"
      type="distance"
    >
      <name language="en">Example</name>
    </field>
    

    Screenshot Screenshot

    Type Float

    A floating point integer.

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roof.example"
      type="float"
    >
      <name language="en">Example</name>
    </field>
    

    Screenshot

    Attribute Description
    min Minimum value that can be entered.
    max Maximum value that can be entered.

    Type Integer

    An integer number.

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roof.example"
      type="int"
    >
      <name language="en">Example</name>
    </field>
    

    Screenshot

    Attribute Description
    min Minimum value that can be entered.
    max Maximum value that can be entered.

    Type Slider

    A value between 0.0 and 1.0 editable using a slider.

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roof.titleSeparator"
      type="slider"
    />
    

    Type Image

    The file name of a file containing an image.

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roof.titleSeparator"
      type="image"
      multiplicity="*"
    />
    

    Screenshot

    Attribute Description
    multiplicity Determines how many images can be added:
    +: one or more images
    *: zero or more images.
    If the attribute is omitted, only a single image can be added.

    Type Color

    A RGB color presented as a color picker.

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roof.titleSeparator"
      type="color"
    />
    

    Screenshot

    Type Date

    A date formatted as YYYY-MM-DD.

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roof.titleSeparator"
      type="date"
    />
    

    Screenshot

    Type Time

    Time of day formatted as HH:MM:SS.

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roof.titleSeparator"
      type="time"
    />
    

    Type Separator

    A line in a form separating the previous fields from the ones that follow.

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roof.titleSeparator"
      type="separator"
    />
    

    Screenshot

    Type Disclosure

    A conditional fieldset that hides or shows other fields while retaining their values. This field is used to show or hide multiple other fields with one condition. In addition, the values of those fields are exported to the floor plan xml regardless of whether or not the condition of the fieldset matches.

    <?xml version="1.0" encoding="UTF-8"?>
    <field
      id="roof.titleSeparator"
      type="disclosure"
    />
    

    3D Symbols

    When adding symbols to a room, magicplan distinguishes between two types of items:

    1. Floor items: can be positioned anywhere in a room.
    2. Wall items: a wall must be selected first.

    The position of the pivot or the rotation of a 3D model depend on the type of item it represents.

    As a general rule, in case an item is composed of multiple parts, the bounding boxes shown in the examples below refer to the entire item, i.e. comprising all of its parts.

    Pivot

    Floor items

    The pivot for these items should be positioned as in the following picture:

    Screenshot

    Wall items

    The pivot for these models should be positioned as in the following picture:

    Screenshot

    Rotation

    Floor items

    For floor items it is worth making a distinction between axis of rotation.

    Around Z-axis: An angle of rotation around this axis can be assigned within the app while editing the plan in 2D and it's trivially the only rotation visible in the 2D. Regarding the initial orientation around the Z-axis two different cases exist:

    Taking into account the coordinate system used inside magicplan (top right in the next picture), it is easy to see that the headboard of the bed points towards the negative Y-axis (or, on the contrary, the foot points towards the positive Y-axis): the 3D model of the bed, must have the same orientation.

    Around X/Y-axis: The model should be built in such a way as to guarantee that the surface of the item that touches the ground (where the pivot is placed) lies on the XY plane.

    Wall items

    To define wall-mounted item rotation, it is important to first define the normal of such an item:

    The back plane of the item is the one used to define the position of the pivot.

    Screenshot

    The default orientation of an item should be such that its normal points toward the negative Y-axis (with respect to magicplan coordinate system).

    Size

    One unit in the 3D modeling environment corresponds to 1mm.

    Export

    The 3D model should be exported as such:

    Geometry and material

    Blake Grey Wash 68" Media Console

    ...
    o Door
    v -359.413513 285.842468 226.055450 v -162.681000 285.842468 226.055450 ...
    vt -0.000000 1.000000
    vt -0.000000 0.000000
    vt 1.000000 0.000000
    ...
    vn 0.000000 0.000000 -1.000000
    vn 0.000000 0.000000 1.000000
    ...
    usemtl fabric
    f 34/33/2 36/34/2 33/35/2
    f 33/36/3 38/37/3 37/38/3
    ...
    
    o Chestofdrawers
    v -825.644714 199.242035 -232.641174 v -825.644714 199.241974 199.700531 ...
    vt 0.103900
    vt 0.068700
    ...
    vn 0.000000
    vn 1.000000
    ...
    usemtl wood
    f 34/33/2 36/34/2 33/35/2
    f 33/36/3 38/37/3 37/38/3
    ...
    

    Material Blake Grey Wash 68" Media Console

    newmtl fabric
    Ns 96.078431
    Ka 1.000000 1.000000 1.000000
    Kd 0.640000 0.640000 0.640000
    Ks 0.500000 0.500000 0.500000
    Ke 0.000000 0.000000 0.000000
    Ni 1.000000
    d 1.000000
    illum 0
    map_Kd BlakeGreyWashRattan_bumf_Map.png
    
    newmtl wood
    Ns 96.078431
    Ka 1.000000 1.000000 1.000000
    Kd 0.640000 0.640000 0.640000
    Ks 0.500000 0.500000 0.500000
    Ke 0.000000 0.000000 0.000000
    Ni 1.000000
    d 1.000000
    illum 0
    map_Bump -s 3.000000 4.000000 1.000000 BlakeGreyWashTeak_bum_Map.png
    map_Kd -s 2.999999 3.999998 0.000000 BlakeGreyWashTeak_dif_Map.png
    

    In case an item consists of multiple parts, all its parts must be exported into a single .OBJ file.

    It is important to export, together with vertices and faces (v and f), the vertices normals vn and texture coordinates vt.

    The materials used in the example (e.g. usemtl fabric ) are defined in the .MTL file associated with the object. There should be a single .mtl file per item. Inside the file different material definitions can exist.

    The correct assignment of all the values to the appropriate parameters will be taken care of by the software performing the export. In case a texture is to be applied to the item, it is important only to note (and make sure) that the parameters concerning textures are present inside the file.

    For example, in the example there have been defined:

    a diffuse texture for the fabric material

    map_Kd BlakeGreyWashRattan_bumf_Map.png

    a diffuse texture for the fabric material

    map_Bump -s 3.000000 4.000000 1.000000 BlakeGreyWashTeak_bum_Map.png

    map_Kd -s 2.999999 3.999998 0.000000 BlakeGreyWashTeak_dif_Map.png

    Code Lists

    Symbol value keys

    This section contains a list of all possible attribute values which can be used when defining default values for a symbol

    Key Description
    sku Any unique string identifying the product in the provider’s database.
    pricingModel none: This item cannot be used by the estimator.
    item: Price per individual item times quantity.
    surface: Price per unit of area times actual area.
    hour: Price per hour times the number of hours.
    distance: Price per unit of distance times actual distance.
    roll: Either price per unit of distance times actual distance OR price per unit of area times actual area.
    surcharge: A percentage of the total price added on top of the total estimated price.
    tax: A percentage of the price of taxable items added on top of the total estimated price.
    elevation: Price based on elevation readings positioned at various positions on the ground. (Specific to one customer, do not include in Price List Manager.)
    boxType The type of packaging the materials are shipped in.
    m: The product is sold by the meter (distance pricingModel only). The exact length is used to compute the price without any rounding.
    ft: The product is sold by the foot (distance pricingModel only). The exact length is used to compute the price without any rounding.
    m2: The product is sold by the square meter (surface pricingModel only). The exact surface area is used to compute the price without any rounding.
    ft2: The product is sold by the square foot (surface pricingModel only). The exact surface area is used to compute the price without any rounding.
    box: The product is sold by the case. Each case has a distance/surface coverage and the estimate shows the number of cases to purchase.
    can: The product is sold by the can. Each can has a distance/surface coverage and the estimate shows the number of cans to purchase.
    tube: The product is sold by the tube. Each tube has a distance/surface coverage and the estimate shows the number of tubes to purchase.
    tile: The product is sold by the tile. Each tile has a surface coverage and the estimate shows the number of tiles to purchase.
    plank: The product is sold by the plank. Each plank has a distance/surface coverage and the estimate shows the number of planks to purchase.
    boxCoverage The distance/surface covered by one case/can/tube/tile/plank of product. Only applies if a boxType is specified.
    distanceReference compute: The length is computed dynamically using a combination of distanceReference
    Perimeter, distanceReferenceDownToFloorItemsWidth, distanceReference
    DoorsAndWindowsWidth.
    customDistance: A user-defined distance that is not the result of a computation, as specified in the distanceValue field.
    distanceReference
    Perimeter
    Set to 1 to include the perimeter of the room, floor, or plan, depending on the nature of the linked objects, excluding all openings.
    distanceReference
    DownToFloorItemsWidth
    Set to 1 to include the width of all openings at floor level. [default: 0]
    distanceReference
    DoorsAndWindowsPerimeter
    Set to 1 to include the perimeter of the linked wall items. [default: 0]
    distanceReference
    DoorsAndWindowsWidth
    Set to 1 to include the width of the linked wall items. [default: 0]
    distanceValue The distance value in the units specified in the distanceUnit value.
    surfaceReference compute: The total surface area is not set by the user, but computed using the values of the surfaceReferenceGround, surfaceReferenceCeiling, surfaceReferenceWalls, surfaceReferenceWallsHeight, and surfaceReferenceOpenings fields.
    customSurface: The user entered a custom value for the surface area, as specified in the surfaceValue field. customDrawnSurface: The user drew a polygon on the ground to measure the surface area. The value is in the surfaceValue field.
    surfaceReference
    Ground
    Include the area of the ground in the surface computation if set to 1.
    surfaceReference
    Ceiling
    Include the area of the ceiling in the surface computation if set to 1.
    surfaceReference
    Walls
    Include the area of the selected walls in the surface computation if set to 1.
    surfaceReference
    PartialWallsHeight
    If set to 1, use the value of the surfaceReferenceWallsHeight field when computing the wall area. If not, use the wall height of the room (or floor, or plan).
    surfaceReference
    WallsHeight
    Use this height when computing the wall area if specified.
    surfaceReference
    Openings
    Include the area of the wall openings in the surface computation if set to 1.
    volumeUnit l: litres
    g: gallons
    weightOf customWeight: A custom weight that is not the result of a computation, specified in the weightValue field.
    weightValue The weight in units specified in the weightUnit field.
    weightUnit kg: kilograms
    lb: pounds
    rollUnit ft: feet
    in: inches
    m: metres
    cm: centimetres
    ft2: square feet
    in2: square inches
    m2: square metres
    cm2: square centimetres
    hourCount The number of hours.
    percentage The percentage value for taxes and surcharges.
    wallItemDistanceToFloor For wall items only.
    The distance between the floor and the bottom of the wall item.

    Predefined Categories

    These categories are already defined and can be used when defining new symbols:

    Code Description
    roomitems Assigns default fields to objects that can be moved on the floor such as pieces of furniture, including label, 3 dimensions, photos, and notes.
    wallitems Assigns default fields to objects that can be attached to a wall such as doors and windows, including label, 2 dimensions, distance to floor, photos, and notes.
    csiitems Give user control over objects annotation numbering.
    abstractitems Objects with no physical dimensions, such as annotations and evacuation symbols. These objects only have labels, photos, and notes.
    wireitems Linear objects that have a line type, a color, and a thickness, such as wires and pipes.
    smallitems Small room items that can be placed on top of other objects, such as plants and photocopiers. These objects also have a distance to floor on top of all other attributes.

    Predefined Forms

    When defining a new item, adding it to the following forms provides some common functionality. The déclarations in the examples below can contain multiple symbols or even categories.

    Image Form

    <form id="z-imageForm">
      <field id="notes" type="multitext">
        <name language="en">Notes</name>
      </field>
      <field id="image" type="image" multiplicity="+">
        <name language="en">Photo</name>
      </field>
    </form>
    

    To add support for images and notes, add the item to the z-imageForm.

    Screenshot

    Label Form

    <form id="b-labelForm">
      <field id="displaylabel" class="displayLabel" type="list" default="never"annotation="never">
        <name language="de">Namen anzeigen</name>
        <option value="never">
          <name language="en">Never</name>
        </option>
        <option value="above">
          <name language="en">Above the object</name>
        </option>
        <option value="over">
          <name language="en">Over the object</name>
        </option>
        <option value="below">
          <name language="en">Below the object</name>
        </option>
      </field>
      <field id="label" annotation="never">
        <name language="en">Label</name>
      </field>
    </form>
    

    To add support for label display and editing, add the item to the b-labelForm.

    Screenshot

    Available types of floor

    Code Description
    -3 3rd Basement
    -2 2rd Basement
    -1 1rd Basement
    0 Ground Floor
    1 1st Floor
    2 2nd Floor
    3 3rd Floor
    ...
    50 50th Floor
    1000 Roof
    2000 Land survey

    Predefined list of residential rooms

    Predefined list of commercial rooms

    Symbols

    This section contains a list of all the symbol identifiers supported in the current version of magicplan, along with their visual representation. Symbols are grouped under the categories available in the app. The first line of text contains the English name as it appears in the app and the second line the symbol unique ID as it appears in XML files.

    Doors

    Windows

    Appliances

    Furniture

    Electrical (North America)

    Electrical (International)

    Alarm & Security

    Garage

    Structure

    HVAC

    Plumbing

    Kitchen Cabinets (North America)

    Kitchen Cabinets (International)

    Fire & Safety

    Office

    Outdoors