Getting Started
Using email
1. Configure the export button
Sign in to the magicplan Cloud as a Workspace admin and go to the settings of your Workspace.
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 projects should be sent to.
Save your configuration.
2. Invite magicplan user to your workspace (optional).
In order for a user to test the export, they need to be in your workspace. If necessary you can invite additional users to your workspace.
Sign in to the magicplan Cloud as a Workspace admin and go to your Workspace members list.
You can invite additional members to your workspace using the "Invite user" button (1).
Enter the email address of the user you would like to invite and press "Invite".
3. Create and publish a project.
Sign in to magicplan using an account that is part of the workspace, create a project and export it to your application using your application's export button.
When the magicplan user publishes the project, magicplan will send an email to the email address configured on the magicplan Cloud.
Using HTTP
1. Setup HTTPS endpoints.
This is the endpoint that will receive the project 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.
Go to the API & Integrations page on the magicplan Cloud and generate your API_SECRET_KEY
and the CUSTOMER_ID
.
In order to configure the URL from step 1, you need to send an email to integration@magicplan.app, providing the URL that you want to use.
This guide uses CUSTOMER_ID
and API_SECRET_KEY
as placeholders. You will need to replace placeholders with the values you generated via magicplan Cloud.
3. Configure the export button
Sign in to the magicplan Cloud as a Workspace admin and go to the settings of your Workspace.
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 projects 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 workspace and therefore they will see the export button right away.
5. Create and publish a project.
Sign in to magicplan using the test account, create a project and export it to your application using your application's 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&
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 project, magicplan will send a GET
request to the receive endpoint. The request will contain the URL of the project 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
Link account
Before a user in magicplan can send projects 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.
For a user to become part of your workspace, you need to have an empty subscription seat into your workspace, which will be then assigned to your user. You can manage your subscription on the magicplan cloud, under the Billing Page. Once the user is linked to your workspace, they will also get a subscription seat assigned automatically.
HTTP Request
POST https://cloud.sensopia.com/newuser.php
Request
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 generated on the magicplan Cloud. |
key | Yes | The API key generated on the magicplan Cloud. |
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. |
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="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. | |
48 | We could not find an empty seat to assign it to this account. Please add a seat to your billing first. | |
49 | sWe could not find an active subscription for this workspace. | |
<message> |
A human readable representation of the response |
Unlink account
Use this request to unlink any user account that has been previously linked to magicplan. Once the user is unlinked from your workspace, the subscription seat will also get unassigned from this user.
HTTP Request
POST https://cloud.sensopia.com/deleteuser.php
Request
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 generated on the magicplan Cloud. |
key | Yes | The API key generated on the magicplan Cloud. |
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. |
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="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. | |
50 | There is a subscription seat assigned to this user. Please go to magicplan cloud to un-assign the seat and remove this member from your workspace. | |
<message> |
A human readable representation of the response |
Link account options
To link a magicplan account with the user account of your platform, there are three options:
-
Via Single Sign On: If you have all of your user accounts centralised in one place (for example Azure AD, Salesforce etc), you can reach out to magicplan's Integrations team and ask them to configure SSO for your main workspace.
-
Via OAuth 2.0: magicplan supports OAuth 2.0 with the Authorization Code grant. If your application supports OAuth too, you can reach out to magicplan's Integrations team and ask them to configure OAuth for your main workspace. If you want to see how OAuth works in magicplan, you can go ahead and enable Floorplanner or PlanGrid integration under API & Integrations page on the magicplan Cloud and evaluate it whether that is something you would also want to have for your integration.
-
Via Link account API which is explained above.
To reach out to the Integrations team for configuring one of the first two options above, please send an email to integration@magicplan.app and specify the workspace owner account or the workspace name.
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 generated on the magicplan Cloud. |
key | Yes | The API key generated on the magicplan Cloud. |
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 |
Workspace API
Workspace API gives you access to more information about users and projects of your workspace. A detailed documentation of the response format and request parameters can be found in our SwaggerHub documentation.
Workspace users
This request provides you with a list of all users that are part of your workspace.
For example, you may want to know or monitor the number of users that are in your workspace. To retrieve that information, you can use this request. The response is a paginated list, with a page size of 100 items.
HTTP Request
GET https://cloud.magicplan.app/api/v2/workgroups/users
A more detailed documentation can be found in our SwaggerHub Documentation.
Workspace projects
You may want to fetch information about projects that belong to you and/or users that are part of your workspace. You can also use this request, to retrieve the ID of your workspace projects, and then fetch more detailed information for those projects.
This request provides you with a list of all projects of your workspace. The response is a paginated list, with a page size of 100 items. You can have a specific filtered and sorted result based on your needs.
A more detailed documentation can be found in our SwaggerHub Documentation.
HTTP Request
GET https://cloud.magicplan.app/api/v2/workgroups/plans
Project API
Create project
This request creates an empty project with a list of attributes and dispatches it to a given user. Attributes can only be attached to the project itself (as opposed to objects inside the project) and the project does not contain any rooms initially.
For example, you can use this to prepare new projects 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 generated on the magicplan Cloud. |
key | Yes | The API key generated on the magicplan Cloud. |
Yes | The user's email address. magicplan uses it as a login. | |
type | Yes | The type of project to create (0=Residential, 1=Commercial) |
name | Yes | The name of the project. |
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 project. If specified, this ID is passed back to your application when exporting the project. 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 . |
|
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 project id of the created project |
List project files
This request returns all files associated with a given project or to all projects belonging to a given user.
Note: This API will only return the files that are generated after your users have exported the project to your application using your application's export button.
To filter the api result, there are two options:
-
To retrieve all files associated with a known project, specify the project unique identifier in the
planid
parameter and omit theemail
parameter. Theplanid
can be obtained from magicplan when creating a new project. -
To retrieve all files belonging to a known user, specify the user’s email address in the
email
parameter and omit theplanid
parameter.
Sequence
HTTP Request
POST https://cloud.sensopia.com/listfiles.php
Request
List all files for a project
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 generated on the magicplan Cloud. |
key | Yes | The API key generated on the magicplan Cloud. |
planid | No | The unique identifier of the project the files are associated with. If specified, the most recent copy of the files based on the given project are returned. The project must belong to a member of the given customer’s workspace. |
No | The user's email address. The user must be a member of the given customer’s workspace. | |
since | No | Unix timestamp, a date in seconds since 1970-01-01. All files returned will be more recent than the given date. |
filetype | No | Value should be set to picture , in order to fetch user generated images that have been attached to the project / floors / rooms / objects. |
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 . |
|
7 | The email address is invalid or unspecified. | |
14 | There is no user with the given email address. | |
36 | There are no files generated for the given planid |
|
43 | One of the parameters is invalid. | |
<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 project.
Attribute | Description |
---|---|
url |
The public URL from which the file can be downloaded. |
id |
The id of the project 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 example
<?xml version="1.0" encoding="UTF-8"?>
<symbolInstance
id="F-0-0"
uid="5aec8337.df981ffc"
parentUid=""
symbol="chair"
>
<values>
<value key="image[0]">img0.jpg</value>
<value key="image[1]">img2.jpg</value>
<value key="image[2]">img4.jpg</value>
</values>
</symbolInstance>
<floorRoom
type="Living Room"
uid="5bc6edb3.ed799cff"
...
>
<values>
<value key="floor">1</value>
<value key="image[0]">img1.jpg</value>
<value key="image[1]">img3.jpg</value>
</values>
</floorRoom>
When processing the project xml, you might want to download user generated images that have been attached to the project / floors / rooms / objects.
You can do that, by calling listfiles service and passing filetype = picture
as a parameter.
For example:
-
A user exports a project using your application's export button.
-
You get all project files via the update webhook.
-
Then you call listfiles service, and pass the
picture
filetype. -
If needed, you can store all images on your system.
-
In order to get information on where the picture are referenced, you will need to parse the project xml.
List all images for a project
POST /listfiles.php HTTP/1.1
Host: cloud.sensopia.com
Content-Type: application/x-www-form-urlencoded
customer=3b2abe7cd80d&
key=2aB193beHa42t1o09aqbJm3HFp1M3b8&
planid=456dsf254a35
filetype=picture
Response example
<?xml version="1.0" encoding="UTF-8"?>
<MagicPlanService>
<file
id='456dsf254a35'
url='https://s3.amazonaws.com/prod.plans.sensopia.com/456dsf254a35/img0.jpg?AWSAccessKeyId=AKIAIWFBP33V545VAYIQ&Expires=1566571490&Signature=xifQoIP%2BsGEzW2bsHFbB2B5uKSI%3D'
name='img0.jpg' date='1566467565' type='jpg' />
<file
id='456dsf254a35'
url='https://s3.amazonaws.com/prod.plans.sensopia.com/456dsf254a35/img1.jpg?AWSAccessKeyId=AKIAIWFBP33V545VAYIQ&Expires=1566571490&Signature=v10dqNezziMdXyaf%2FIASd4wfVZQ%3D'
name='img1.jpg' date='1566467565' type='jpg' />
<file
id='456dsf254a35'
url='https://s3.amazonaws.com/prod.plans.sensopia.com/456dsf254a35/img2.jpg?AWSAccessKeyId=AKIAIWFBP33V545VAYIQ&Expires=1566571490&Signature=SqRK3oRGdPlVOg8MIZIr6023I6E%3D'
name='img2.jpg' date='1566467565' type='jpg' />
<file
id='456dsf254a35'
url='https://s3.amazonaws.com/prod.plans.sensopia.com/456dsf254a35/img3.jpg?AWSAccessKeyId=AKIAIWFBP33V545VAYIQ&Expires=1566571490&Signature=w%2FQUHpgYABQIivy79GXajWrdIms%3D'
name='img3.jpg' date='1566467565' type='jpg' />
<file
id='456dsf254a35'
url='https://s3.amazonaws.com/prod.plans.sensopia.com/456dsf254a35/img4.jpg?AWSAccessKeyId=AKIAIWFBP33V545VAYIQ&Expires=1566571490&Signature=tBNlupfl1xxlxYjUGp4woe6hPXE%3D'
name='img4.jpg' date='1566467565' type='jpg' />
<service>listfiles</service>
<status>0</status>
</MagicPlanService>
Fetch project details
This request returns a detailed representation of the project contents.
For example, you could retrieve all your projects and then get more information for each specific project.
You can retrieve estimation of the project, measurement data, coordinates, notes, images, survey answers, the XML file of the project itself (in case that fits more to your needs) and lots of more information about the project.
For more information about request parameters and response, please check into our SwaggerHub Documentation.
HTTP Request
GET https://cloud.magicplan.app/api/v2/plans/get/{id}
Fetch project statistics
This request returns a detailed representation of the project statistics / measurements.
For more information about request parameters and response, please check into our SwaggerHub Documentation.
HTTP Request
GET https://cloud.magicplan.app/api/v2/plans/statistics/{id}
Receive Project API
Link project
Exporting projects 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 projects that are not already linked to a project prior to exporting that project.
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, projects 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.
HTTP Request
GET https://yourserverurl/getlistings
Request
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 magicplan |
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. |
Response
<?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 they 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. |
Create new 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 they published their project. 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 project to your application. Per default magicplan will authorize all projects.
If this service is configured, magicplan calls it when a user requests the right to publish a project. Once your application receives this request, you may accept or decline the transfer, based on your own account and payment information.
-
In case of acceptation, you must return a confirmation number that magicplan logs to allow further payment reconciliation. magicplan then calls the update webhook to notify your application that the files are ready to download. If the user updates a project that has already been paid for and published, the service is called again to verify that you are still allowing this user to publish. Your application should issue the same confirmation number and not charge the user for the update.
-
In case of refusal, no confirmation number is returned and magicplan does not call the update webhook.
If the user has previously selected a project or the project 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 magicplan |
Yes | The user's email address. | |
ref | Yes | The unique reference string that you passed when creating the user. |
listing | No | The ID of your local project that has been assigned to the magicplan project. |
planid | Yes | The unique identifier of the project 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. |
Project 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. The file URLs are only valid for 60min.
If the request fails, the user in magicplan will see an error and is able to retry publishing the project.
Depending on your configuration the request includes several file types representing the exported project. For worldwide interoperability each string or file url is encoded in a two-step process:
- The character string is converted into a sequence of bytes using UTF-8 encoding.
- 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
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&
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 magicplan |
Yes | The user's email address. | |
ref | Yes | The unique reference string that you passed when creating the user. |
title | Yes | A human-readable title of the projects being updated. |
planid | Yes | The unique identifier of the project being updated. |
listing | No | The ID of your local project that has been assigned to the magicplan project. |
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. |
svg0, svg1, ... svgF | 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). |
ifc | No | The URL of the IFC file of your entire project. |
usdz | No | The URL of the USDZ file of your entire project. |
obj | No | The URL of the OBJ file of your entire project. |
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="14"/>
<xs:enumeration value="18"/>
</xs:restriction>
</xs:simpleType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
XML tag | Value | |
---|---|---|
<status> |
0 | The request was a success. |
1 | The API key is invalid. | |
14 | The given user reference or email does not exist. | |
18 | The given listing does not exist. |
User generated images
XML example
<?xml version="1.0" encoding="UTF-8"?>
<symbolInstance
id="F-0-0"
uid="5aec8337.df981ffc"
parentUid=""
symbol="chair"
>
<values>
<value key="image[0]">img0.jpg</value>
<value key="image[1]">img2.jpg</value>
<value key="image[2]">img4.jpg</value>
</values>
</symbolInstance>
<floorRoom
type="Living Room"
uid="5bc6edb3.ed799cff"
...
>
<values>
<value key="floor">1</value>
<value key="image[0]">img1.jpg</value>
<value key="image[1]">img3.jpg</value>
</values>
</floorRoom>
When processing the project xml, you might want to download user generated images that have been attached to the project / floors / rooms / objects.
You can do that, by calling listfiles service and passing filetype = picture
as a parameter.
For example:
-
A user exports a project using your application's export button.
-
You get all project files via the update webhook.
-
Then you call listfiles service, and pass the
picture
filetype. -
If needed, you can store all images on your system.
-
In order to get information on where the picture are referenced, you will need to parse the project xml.
List all images for a project
POST /listfiles.php HTTP/1.1
Host: cloud.sensopia.com
Content-Type: application/x-www-form-urlencoded
customer=3b2abe7cd80d&
key=2aB193beHa42t1o09aqbJm3HFp1M3b8&
planid=456dsf254a35
filetype=picture
Response example
<?xml version="1.0" encoding="UTF-8"?>
<MagicPlanService>
<file
id='456dsf254a35'
url='https://s3.amazonaws.com/prod.plans.sensopia.com/456dsf254a35/img0.jpg?AWSAccessKeyId=AKIAIWFBP33V545VAYIQ&Expires=1566571490&Signature=xifQoIP%2BsGEzW2bsHFbB2B5uKSI%3D'
name='img0.jpg' date='1566467565' type='jpg' />
<file
id='456dsf254a35'
url='https://s3.amazonaws.com/prod.plans.sensopia.com/456dsf254a35/img1.jpg?AWSAccessKeyId=AKIAIWFBP33V545VAYIQ&Expires=1566571490&Signature=v10dqNezziMdXyaf%2FIASd4wfVZQ%3D'
name='img1.jpg' date='1566467565' type='jpg' />
<file
id='456dsf254a35'
url='https://s3.amazonaws.com/prod.plans.sensopia.com/456dsf254a35/img2.jpg?AWSAccessKeyId=AKIAIWFBP33V545VAYIQ&Expires=1566571490&Signature=SqRK3oRGdPlVOg8MIZIr6023I6E%3D'
name='img2.jpg' date='1566467565' type='jpg' />
<file
id='456dsf254a35'
url='https://s3.amazonaws.com/prod.plans.sensopia.com/456dsf254a35/img3.jpg?AWSAccessKeyId=AKIAIWFBP33V545VAYIQ&Expires=1566571490&Signature=w%2FQUHpgYABQIivy79GXajWrdIms%3D'
name='img3.jpg' date='1566467565' type='jpg' />
<file
id='456dsf254a35'
url='https://s3.amazonaws.com/prod.plans.sensopia.com/456dsf254a35/img4.jpg?AWSAccessKeyId=AKIAIWFBP33V545VAYIQ&Expires=1566571490&Signature=tBNlupfl1xxlxYjUGp4woe6hPXE%3D'
name='img4.jpg' date='1566467565' type='jpg' />
<service>listfiles</service>
<status>0</status>
</MagicPlanService>
Deep Linking
magicplanstd://open?plan={planid}&showInfo=1
Deep linking allows users to navigate through magicplan and your application automatically.
For example, let's say you have added a button somewhere in your application and called it "Capture with magicplan". You would connect the magicplan deep link to this button, so that when your user taps on the button, magicplan app will open automatically and will redirect the user straight to the project view.
magicplan can also redirect the user into your platform automatically once the user exports the project successfully into your application. For that, you would need to share your deep link (or an HTTP URL) with the magicplan's Integration Team.
We suggest a user workflow like the one below, but of course you are free to implement any type of workflow that would work for your use case:
- User goes into your application and creates a project / job (depending on how you call it on your app).
- Once the user is done defining the project into your app, they would tap on the button "Capture with magicplan". This button needs to be implemented into your platform.
- On this step, you will have to call Create Project API and use the
planid
value for the deep link at the next step. However, this doesn't have to happen exactly on this step. You can also create a project in magicplan (and store the id) right after a project/job is created on your application. The goal is to have theplanid
ready once you need to launch the magicplan app. - Once you have the
plaind
, you can now call the deep link and pass the id into the link. - magicplan app will launch.
- User will capture the rooms and maybe place objects into the project. Once they are done with the project, they will go ahead and export the project back to your application via your export button.
- magicplan will then call your webhook and send you the URLs of all the files that got generated for the project that got exported
- If your application returns a successful response, magicplan will redirect the user automatically to your app (or a specific HTTP URL).
Project XML
The following section describes the XML format of a magicplan file. Each file contains all the projects 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 projects of various floors.
Project
<?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.
Attribute | Description |
---|---|
id |
A unique identifier of the project as assigned by magicplan. |
name |
The human-readable name of the project. This is the same text as the title parameter mentioned in the Web Services documentation. |
type |
The type of project: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
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 <project>
-element contains a list of <floor>
-elements representing the project for each floor.
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. |
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 project:
-
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 convenient for drawing the floor when you only need a line drawing without the room nomenclature. -
A list of
<floorRoom>
-elements describe each room individually. Connecting walls and doors are described twice in this format, once for each room. This representation is semantically rich and allows determining in which room lies any[x, y]
coordinate on the project.
In both representations, the coordinates of a wall are positioned on an imaginary line located at the center of the wall, see also Point. To compute the length of the wall surface you need to offset these points from the center of the wall to the wall’s surface.
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.
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" height="2.5000"/>
<point x="-5.912" y="-2.927" height="2.5000"/>
<type>exterior<type/>
</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:attribute name="height" type="xs:decimal"/>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
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. To compute the length of the wall surface you need to offset these points from the center of the wall to the wall’s surface.
Attribute | Description |
---|---|
x |
The corrected horizontal position of the corner relatively to the center of the project, in meters, as a floating point number. This value should be used when drawing an assembled project. |
y |
The corrected vertical position of the corner relatively to the center of the project, in meters, as a floating point number. This value should be used when drawing an assembled project. |
height |
The height of the wall in meters, as a floating point number. |
Type
The type can be either exterior
or interior
. See below more about the difference between these two types.
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).
Wall thickness
The thickness of the wall can be obtained from the <project>
-element (see Project) and its respective attributes interiorWallWidth
(1) and exteriorWallWidth
(2).
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"
depth="0.200"
height="1.985"
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="depth" type="xs:decimal" use="required"/>
<xs:attribute name="height" 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.
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 project, in meters, as a floating point number. |
y1 |
The vertical position of the first extremity of the door relatively to the center of the project, in meters, as a floating point number. |
x2 |
The horizontal position of the second extremity of the door relatively to the center of the project, in meters, as a floating point number. |
y2 |
The vertical position of the second extremity of the door relatively to the center of the project, 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 project. |
depth |
The depth of the door in meters, as a floating point number. |
height |
The height of the door in meters, as a floating point number. |
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 project. 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"
depth="0.100"
height="1.985"
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="depth" type="xs:decimal" use="required"/>
<xs:attribute name="height" 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.
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 project, in meters, as a floating point number. |
y1 |
The vertical position of the first extremity of the window relatively to the center of the project, in meters, as a floating point number. |
x2 |
The horizontal position of the second extremity of the window relatively to the center of the project, in meters, as a floating point number. |
y2 |
The vertical position of the second extremity of the window relatively to the center of the project, 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 project. |
depth |
The depth of the window in meters, as a floating point number. |
height |
The height of the window in meters, as a floating point number. |
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 project. |
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"
height="0.537"
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="height" 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.
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 project, in meters, as a floating point number. |
y |
The vertical position of the piece of furniture relatively to the center of the project, 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. |
height |
The height 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
<?xml version="1.0" encoding="UTF-8"?>
<floor>
<floorRoom type="Hall"> … </floorRoom>
<floorRoom type="Bathroom"> … </floorRoom>
<floorRoom type="Kitchen"> … </floorRoom>
…
</floor>
Each <floor>
-element can contain multiple rooms (<floorRoom>
).
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>
Attribute | Description |
---|---|
uid |
Unique id of a room as assigned by magicplan 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 project in meters as a floating point number. |
y |
The vertical position of the center of the room on the project 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. To compute the length of the wall surface you need to offset these points from the center of the wall to the wall’s surface.
The list of points are ordered clockwise.
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 project. |
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 project. |
Wide Opening
<?xml version="1.0" encoding="UTF-8"?>
<wideOpening
symbolInstance="W-0-0"
point="2"
snappedPosition="0.50000"
snappedWidth="3.06705"
snappedDepth="0.12000"
snappedHeight="2.04000"
/>
<xs:element name="wideOpening">
<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="snappedDepth" type="xs:decimal" use="required"/>
<xs:attribute name="snappedHeight" type="xs:decimal" use="required"/>
</xs:complexType>
</xs:element>
<xs:simpleType name="position">
<xs:restriction base="xs:decimal">
<xs:minInclusive value="0.0"/>
<xs:maxInclusive value="1.0"/>
</xs:restriction>
</xs:simpleType>
The <wideOpening>
-element represents a wall that has been removed in the current room.
Attribute | Description |
---|---|
symbolInstance |
The unique identifier of the <symbolInstance> element containing data attached to this opening. The symbol instance contains the symbol ID. |
point |
The index 0-based of the <point> element starting the opening. |
snappedPosition |
The corrected relative position of the opening represented by a floating point number between 0.0 and 1.0. This value should be used when drawing an assembled project. |
snappedWidth |
The corrected width of the opening in meters represented by a floating point number. This value should be used when drawing an assembled project. |
snappedDepth |
The corrected depth of the opening in meters represented by a floating point number. This value should be used when drawing an assembled project. |
snappedHeight |
The corrected height of the opening in meters represented by a floating point number. This value should be used when drawing an assembled project. |
Door
<?xml version="1.0" encoding="UTF-8"?>
<door
symbolInstance="W-2-1"
point="3"
snappedPosition="0.68850"
snappedWidth="0.75000"
snappedOrientation="0"
insetY="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="insetY" 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.
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 project. |
snappedWidth |
The corrected width of the door in meters represented by a floating point number. This value should be used when drawing an assembled project. |
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 project. 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. |
insetY |
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 middle of the wall and into the room. Negative values show that the object goes further inside the wall. |
Window
<?xml version="1.0" encoding="UTF-8"?>
<window
symbolInstance="W-0-0"
point="6"
snappedPosition="0.67558"
snappedWidth="1.28213"
snappedOrientation="0"
insetY="0.0"
/>
<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="insetY" 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.
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 project. |
snappedWidth |
The corrected width of the window in meters represented by a floating point number. This value should be used when drawing an assembled project. |
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 project. 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. |
insetY |
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 middle of the wall and into the room. Negative values show that the object goes further inside the wall. |
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.
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 project, in meters, as a floating point number. This value should be used when drawing an assembled project. |
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 project. |
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 project. |
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 project. |
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>
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 roompoint-wallitem : the wire is attached to a point on a wall itempoint-furniture : the wire is attached to a point on a piece of furnituresegment-room : the wire is attached to a wall of the roomsegment-wallitem : the wire is attached to a segment on a wall itemsegment-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 electricityplumbing : 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 project, 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 magicplan 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 project.
For instance, a door can be represented by up to three <door>
-elements:
- one in the first room,
- one in the adjacent room,
- and one in the exploded section describing the location of the door on the whole floor.
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"
/>
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"
/>
Same door in exploded project
<?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"
/>
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 project. 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 project. The id is shown on 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>
You can also add custom attributes right from within the magicplan user interface. In this case the key
will 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 project (<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>
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>
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>
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>
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>
Project
<?xml version="1.0" encoding="UTF-8"?>
<plan>
<values>
<value key="date">2018-05-04</value>
</values>
</plan>
Room
<?xml version="1.0" encoding="UTF-8"?>
<floorRoom>
<label>Kitchenette</label>
<values>
<value key="notes">Notes here</value>
</values>
</floorRoom>
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.
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>
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>
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 workspace 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.
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 project, 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 project, 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 project, 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>
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>
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. |
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.
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.
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.
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.
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. For example, if you would like to center the object directly onto the wall, you can use (default interior wall thickness / 2) . |
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 project. 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 project 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.
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 project. 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.
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.
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.
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.
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.
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.
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.
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 project.
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> . |
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. |
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. |
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 on 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"
required="1"
>
<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="required" type="xs:byte"/>
<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 project 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. |
required |
Determines if a field is mandatory. This parameter can be set to:1 : Field is mandatory.0 : Field is not mandatory. |
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. |
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>
OR
<?xml version="1.0" encoding="UTF-8"?>
<form id="roof">
<symbol id="plan"/>
<symbol id="room"/>
<field id="roof.isDamaged" type="bool" if="(symbolID=='room')">
<name language="en">Roof damaged</name>
</field>
</form>
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>
Depending on the default value of the field, the value entered by the user might not be exported in the project xml.
-
If the field does not have a default value, it will always be included in the export as either
true
orfalse
. -
If the field has a default value, it depends whether or not the value entered by the user matches the default value. If the value entered by the user is different from the default value, it is included in the export, otherwise it is excluded from the export.
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>
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. |
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>
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>
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>
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>
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>
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="*"
/>
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"
/>
Type Date
A date formatted as YYYY-MM-DD.
<?xml version="1.0" encoding="UTF-8"?>
<field
id="roof.titleSeparator"
type="date"
/>
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"
/>
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 project 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:
- Floor items: can be positioned anywhere in a room.
- 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:
Wall items
The pivot for these models should be positioned as in the following picture:
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 project 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:
-
the item does not exist inside magicplan yet: the initial rotation around the Z-axis is then arbitrary.
-
the item exists already as a magiplan symbol: it is important to make sure that the initial rotation of the 3D item corresponds to that of the 2D symbol. Consider the following picture, representing a bed item in magicplan:
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 projecte.
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.
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 export format .OBJ
- material export format .MTL
- exported file size < 1MB (on average)
- set the Y-axis as the upwards axis in the export settings
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 project, 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 project). |
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
.
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
.
Available types of floor
Code | Description |
---|---|
-3 |
3rd Basement |
-2 |
2nd Basement |
-1 |
1st 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
- Kitchen
- Dining Room
- Living Room
- Hall
- Master Bedroom
- Bedroom
- Bathroom
- Closet
- Study
- Music Room
- Balcony
- Garage
- Corridor
- Laundry Room
- Playroom
- Cellar
- Workshop
- Stairway
- Furnace Room
- Toilet
- Vestibule
- Other
- Hatched Room
Predefined list of commercial rooms
- Private Office
- Shared Office
- Open Space
- Meeting Room
- Conference Room
- Reception
- Kitchenette
- Cafeteria
- Hall
- Closet
- Balcony
- Garage
- Corridor
- Lounge
- Waiting Room
- Workshop
- Training Room
- Stairway
- Maintenance Room
- Storage
- Archives
- Photocopy Room
- Lab
- Server Room
- Elevators
- Furnace Room
- Toilet
- Vestibule
- Other
- Hatched Room
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.